General usage
1.0 Quick start
Tkmedit is started by one of two methods: using the tkmedit-sess script, or invoking it from the command line with the tkmedit command. Depending on which method you use, you may see different types of data loaded, but all methods require an anatomical data set to be loaded. Other types of data can be loaded from the File menu.
To explore your data, you can move the mouse over the picture of the volume (the Display Window) and see information about the area under the mouse in the window on the bottom (the Tools Window). You can change the view with the orientation buttons (the ones shaped like cross-sections of the head labeled 'C,' 'H,' and 'S,' which stand for Coronal, Horizontal and Sagittal) and the slice number field in the Navigation Toolbar. To save pictures of your data, go to the Tools menu and select the Save RGB item near the bottom.
2.0 Viewing area
Tkmedit consists of two windows. The top window, called the Display Window, shows the currently displayed slice. Multiple panes can show multiple orientations and configurations. The bottom window, called the Tools Window, contains the controls and feedback information. Here is the interface.
Information about the currently displayed data can be obtained by moving the mouse over the Display window or by clicking to set the cursor. As the mouse is moved in the display window, the mouseover section of the Tools window will display information about the voxel (or volume element) under the tip of the mouse arrow. Alternatively, most tools set the cursor upon clicking with the left button. The Cursor section of the Tools window displays information about the voxel under the cursor. By default, the cursor is drawn as a red cross. Guidelines are drawn on the sides of the Display Window to help locate the cursor.
It is possible to display multiple orientations of data simultaneously in the Display Window. This is done by splitting the window up into multiple viewing panes, each with a different slice, orientation, or other viewing characteristics. The cursor can be linked between so that a click in one pane to set the cursor will update the cursor in all the other panes. There are three built-in configurations: Single View, Multiple Views, and Mosaic View. These can be activated by clicking on the appropriate icon in the Navigation Toolbar ( 
Single, 
Multiple, 
Mosaic) or by choosing the appropriate item in the View menu.
In the latter two views, there is more than one pane in the Display Window. A green border is drawn around the active pane. To make another pane active, click in it to set the cursor. The mouseover section of the Tools Window will only display information about the voxel under the mouse if it is in the active pane.
2.1 Single view
This is the default view. It is the simplest and fastest view for tkmedit to render.
2.2 Multiple views
This viewing mode divides the window into four panes. Each of the three orientations is shown, with one orientation duplicated. This configuration is optimal for viewing all planes around a single point. By default, the cursor is linked so that setting it in one view moves the current slice in all other views to the cursor's location in that view's orientation.
2.3 Mosaic view
When mosaic view is first activated, the volume is sliced up in the orientation of the last active pane. Sixteen panes are created, each showing a different slice in the same orientation. Note that this mode is slow on most machines and is not optimal for 'live' navigation. It is mainly provided as a way to set up a view to be printed or saved to an image file.
3.0 Navigation
3.1 Changing slices
The current slice can be changed with the controls on the right side of the slice label in the Navigation Toolbar, with the mouse button 2 with the Navigation Tool (
), or with the arrow keys. The current orientation can be changed by clicking on the appropriate button in the Navigation Toolbar (
coronal, 
horizontal, or 
sagittal) or by pressing the 'X,' 'Y,' and 'Z' keys.
With the Navigation Tool active, clicking with button 2 in the top half of the screen increases the slice number by 1, and clicking in the bottom half decreases it by 1. Clicking in dragging will continuously change the slice number; dragging up will increase the slice number, dragging down will decrease it.
3.2 Zooming
The view in any pane may be zoomed in to magnify the size of a voxel. The current zoom level is displayed both in the Navigation Toolbar and on the Navigation Toolbar. The zoom level may be changed in three ways:
- By holding down the control key and clicking with button 1 to set the cursor and zoom in, or button 3 to zoom out. This works with any tool active.
- By clicking on the zoom buttons in the toolbar or the zoom slider in the display area, zooming in or out around the cursor but not set the cursor.
- By activating the Navigation Tool and clicking with button 3. Clicking in the top half of the Display window zooms in, and clicking in the bottom half zooms out. Clicking and dragging up continuously zooms in, and dragging down zooms out. This operation does not change the cursor.
3.3 Panning
While zoomed in, you will not be able to see the entire slice. To pan around in the current slice, you may hold down the control key and click with button 2 to set the cursor and re-center, or activate the Navigation Tool and click and drag with button 1 Using that Navigation Tool will not change the cursor.
As you can see, navigation is primarily down in a modal fashion with the Navigation Tool or at any time with the control-click combinations, although the Navigation Tool is more intuitive and also allows slice changing. You will probably benefit from using both methods.
4.0 Cursor
The cursor serves two main purposes. It acts as a central focus point when multiple viewing panes are open, and it selects a voxel whose information will be displayed in the Tools Window. It also serves as a kind of bookmark for sharing cursors with tksurfer, as a centroid for rotation, selecting a voxel to be graphed in the Time Course Window, and other various functions, explained later.
4.1 Linked cursors
When the viewing area is split into multiple panes, each panel may have a separate cursor location. If cursor linking is active, setting the cursor in one panel will set the cursor in all panes. Cursor linking can be activated with the 
button on the Main Toolbar.
For example, in the Multiple Views configuration, setting the cursor in the coronal pane will change the slice in the horizontal and sagittal planes. So the cursor becomes a way of navigating through the volume using the three orientations.
Depending on the viewing configuration, with Linked Cursors active, other attributes are linked as well, including zooming and display flags. In Mosaic View mode, only the in-plane cursor coordinates will be linked, so the slice in each pane will be the same. However, if the slice number is increased in one pane, the slice number will be increased in all other panes.
4.2 Cursor and mouse information
The bottom of the Tools Window displays information about the voxel under the cursor (on the left) and the mouse (on the right). The information displayed depends on the kind of data loaded. If only an anatomical volume is loaded, only the volume index coordinates, volume Talairach coordinates, and volume value will be displayed. (If for some reason a Talairach transform could not be found, RAS (Right Anterior Superior) coordinates will be displayed instead.) The Talairach coordinates reported are based on Matthew Brett's 10/8/1998 non-linear transform from MNI305 space. The MNI305 coordinates are also available, but are turned off by default (select View->Information->MNI Coordinates).
As other data are loaded, more information will appear in this area. For example, if a functional overlay is loaded, the functional overlay value will appear in this area. Alternatively, the data shown can be changed in the View->Information menu.
5.0 Saving images
You can save the contents of the Display Window to a picture file. Tkmedit uses the RGB format, a simple format readable by most image programs. To save a single picture, choose Tools->Save RGB.... You may want to turn off the cursor or other view items in the View menu before saving your picture.
You can also save a series of images with the Tools->Save RGB Series... command. This command steps through slices in the current orientation and saves an image of each. You choose a directory and prefix for the file names as well as the range of slices to step through. For example, if you choose /tmp for the directory, "image" for the prefix, and 5 and 8 for the start and end, it will create /tmp/image005.rgb, /tmp/image006.rgb, /tmp/image007.rgb, and /tmp/image008.rgb.
6.0 Tips
- Most volume input operations can take many different kinds of volumes. If the volume is a bfloat or bshort volume, select one of the .bfloat or .bshort files. If the volume is a COR volume, select the COR-.info file or just enter the directory without any file names.
Tkmedit uses the Tk toolkit (http://www.tcl.tk) for its interface (the 'Tk' in 'tkmedit'). A nice feature of this toolkit is that all the menus are detachable and can become a separate window that stays up all the time. This is particularly useful when using the View menu. Just click on the top line of the menu when it comes down from the menu bar, and a window will take its place.
- Learn the keyboard shortcuts for volume navigation.
- The 'x', 'y', and 'z' keys will change orientations.
- The arrow keys will change slices.
- You can zoom in with Ctrl + (Ctrl-Shift =) and out with Ctrl -.
- You can also jump to the Navigation Tool by hitting the 'n' key and click around the volume, then return to the tool you were using previously.
- If you are using tkmedit with the expected directory structure at the NMR-MGH center, tkmedit will automatically look in certain places for files. See the File Name Substitution section.
- Find yourself using certain toolbars? You can set environment variables to automatically hide or show without using the View menu. Set TKMEDIT_TOOLBAR_MAIN, TKMEDIT_TOOLBAR_NAV, or TKMEDIT_TOOLBAR_RECON to 0 or 1 to hide or show the main, navigation, or reconstruction toolbars, respectively.
- All file dialog boxes have a menu at the top which you can use to jump to specific directories to find data quickly. Additionally, you can specify your own shortcut directory by setting the environment variable FREESURFER_DATA.