|
|
A guide to using FIV April 29, 2005 |
Introduction
The
Functional Image Viewer, also known as FIV, is a tool for visualizing your
functional and anatomic MRI scans. As
such, it replaces the sturdy by rustic xds.
You’ll find that it has some useful features that are lacking in xds, including
explicit Talairach coordinates, scrollable image stacks, multiple slice
orientations, and customizable display modes.
This brief guide provides all of the information you’ll need to become a
savvy FIV user.
FIV
is written in the java programming language, so it runs on any platform for
which a java implementation is available, including Windows, Mac, Linux, and
Sun OS. This guide focuses on the
installation of FIV on the IAC’s Sun workstations. Contact the Congnitive Neuroscience Lab’s tech desk for
more information on running FIV on other machines or platforms. Also, please send all your bug reports,
suggestions, and comments to us.
FIV
uses ImageJ to do much of the
internal image processing. ImageJ is an
open-source, community-supported application developed by Wayne Rasband at the
NIH. It’s small, fast and powerful, so
consider using it for all of your image processing needs.
This
document is available at http://iac.wustl.edu/~cnlweb/protected/fiv.html
Getting started
To start FIV, simply type
‘fiv’ at the command line prompt on any of the IAC’s Sun workstations. A number of command line options are
available and are discussed below. The
most critical options are ‘-a’ and ‘-s’ – they’re used to specify the
activation and structural files that you want to view. For example, to view an activation file
called ‘act.4dfp.img’ overlaid on the structural image file ‘struct.4dfp.img’,
type the following at the command line:
Prompt> fiv –a act.4dfp.img
–s struct.4dfp.img
Since you’ll almost always
want to specify these image files, FIV includes some shortcuts for simplifying
the call. If you omit –a and –s, FIV
assumes that the first argument is the activation file and that the second is
the structural file. So the following
command is identical to the previous one:
Prompt> fiv act.4dfp.img
struct.4dfp.img
Also, if you leave off the
.4dfp and/or .img extensions, FIV fills them in. So the following command is identical to the
previous two:
Prompt> fiv act struct
Additionally, a default
structural image is used if one is not specified at the command line.
To view only a structural
file, issue the following command:
Prompt> fiv –s
struct.4dfp.img
Again, the file extensions
can be omitted, but the –s must be included.
Please be aware:
File formats are discussed more below, but note that FIV works with 4dfp stack
files, not bfloat files and not mosaic files.
So don’t use sl2mgh or mosaic
(or any other programs) to convert your images.
This should cut out a few steps in your processing stream.
Working with FIV
Depending on your mode
settings and the command line options you use (see below), when FIV starts,
you’ll see a view of your images and/or the FIV toolbar (Fig. 1). If the toolbar isn’t visible, click in the
image window and type Ctl-t to open it.
|
|
|
Fig. 1 The FIV toolbar |
The upper left panel includes
components to open a view of your image.
Use the dropdown boxes to the right of the ‘Go’ button to select the
slice orientation and display type, and then click ‘Go’ to bring up the
view. The ‘montage’ display presents a
subset of the slices in a tiled format similar to xds, and the ‘stack’ display
presents the individual slices in your image in a scrollable stack (Fig. 2).
|
|
|
|
Fig. 2 A montage window (left) showing a transverse view and a
stack window (right) showing a
coronal view. |
|
The upper right panel shows
the current activation and structural files and provides buttons for selecting
different files. If you point the mouse
over one the file names and hit the space bar, the complete path of the file
will appear in a popup window.
The bottom left panel of the
toolbar provides buttons to access various tasks and manipulations:
|
|
Saves
the current image window as it appears as a .gif file. |
|
|
Prints
the current image window as it appears. |
|
|
Opens
the preferences/modes dialog. |
|
|
Opens
the information and error log window. |
|
|
Sets
current and subsequent windows to synced mode. Windows in sync mode are affected by
various manipulations, including adjustments to activation range, which
usually affect only the current window.
Also, mouse motion and clicks within an image window are tracked by
the crosshairs and displayed slice in synced stack windows. At startup, FIV is in synced mode. |
|
|
Toggles
visibility of the ImageJ
window. The ImageJ window includes
additional tools for analyzing your images.
Some of the functionality of ImageJ is not currently operable within
FIV. |
|
|
Toggles
the visibility of the crosshairs. |
|
|
Toggles
whether subsequent windows are displayed in radiologic orientation (left
hemisphere on the right.) Current
windows are not affected. A small green letter at the bottom of each window
indicates its orientation. |
|
|
When
depressed, contrast and brightness of the structural image can be adjusted by
dragging the mouse in the image window or with the arrow keys. |
The lower middle panel on the
toolbar is used to specify the range of activation values that is displayed in
the current window(s) and subsequent windows.
You can specify whether positive and/or negative activations are
displayed using the dropdown box. FIV is
agnostic as to what type of data is stored in the activation file you give it,
so you should use threshold values that are appropriate to the statistic that
is represented in the file. Typically,
you’ll want to use files containing z-values or –log p values.
The lower right panel
displays the Talairach coordinates and activation values in your images. To update the display to the values at the
current mouse position, click the left mouse button. Alternatively, if you type Control-B the
values will update continuously as the mouse moves through an image
window. Also, you can press the space
bar to get a popup display of the values at the current mouse position. You can also type coordinates into the
coordinate boxes in the toolbar window to obtain the activation value at the specified
coordinate and to move the crosshairs and displayed slice in the stack windows.
Log window
The
log window includes panels for error and information messages. An
or 
icon will appear briefly in the upper right
corner of the toolbar when FIV writes an information or error message to the
log. Click 
to open the log window
The
information panel logs a couple of important information messages and provides
a convenient place to record notes. To
log the coordinate and activation value (or voxel intensity for an anatomic
image) at the current mouse position, type Control-W. To log the name and path of the current
activation or structural file, point the mouse over the file listing in the
toolbar and type Control-W. To preview
either of these messages in a popup window, hit the space bar. The information panel is editable and can be
saved to a file.
The
error panel receives all FIV, java, and system errors. While some of these errors are harmless;
others are very bad. If you find that a
critical error has occurred, please send the error log to us by clicking on the
‘Submit’ button on the error log panel.
Use the ‘Add comment’ text box to let us know what you were doing at the
time of the error.
A
third panel titled ‘help’ includes a version of this document.
Preferences and modes
In FIV, a mode is a set of
parameters that describe how an image will be loaded and displayed. These parameters include cropping dimensions,
functional thresholds, default structural images, and more. Default modes for each of the typical image
spaces (111, 222, and 333) are already included in FIV. Unless you specify otherwise, the appropriate
default mode will be used when you load an image.
To create your own modes or
customize the default modes, click on the 
button.
A dialog will appear that includes tabs for each of the default and
custom modes. Within each tab you’ll see
all of the parameters that can be adjusted for each mode (some options in the
default modes are not editable.) You’ll
also see a button to add a new mode.
Feel free to add as many modes as you find useful. Mode information is stored in a file called
‘fiv.prefs’ in your home directory and is loaded each time you start FIV.
Modes can be specified at
startup using the –m command-line option (see below.) Modes can also be specified when loading
images from within FIV. Simply select
the desired mode from the list at the bottom of the Open File dialog.
Command-line options
Command-line options are
available to specify how FIV starts up.
Command-line options override the values set in the mode settings
described above. Command-line usage is
as follows:
fiv [-hv] [ [-a] <activation file>]
[[-s] <structural file>]
[-d <displaytype>] [-o <slice
orientation>] [-m <mode>]
[-nosig] [-notool] [-lstat
<number>] [-hstat <number>]
|
[-a <file>] |
Specifies <file> as the activation
image. The –a can be omitted if the
first argument on the command line is the functional image. The file should
be a 4dfp stack. If the '.4dfp' and/or
'.img' extensions are not included in <file>, they will be added
automatically. |
|
[-s <file>] |
Specifies <file> as the structural
image. The –s can be omitted if the
second argument on the command line is the structural image. The file should
be a 4dfp stack. If the '.4dfp' and/or
'.img' extensions are not included in <file>, they will be added
automatically. |
|
[-h,
-help] |
Displays this message. |
|
[-v,
-version] |
Displays some version information. |
|
[-d
<displaytype>] |
Starts viewer with a <displaytype> window
open. Valid display types: 'montage', 'stack'. |
|
[-o
<slice orientation>] |
Display opens showing data sliced at <slice
orientation>.Valid orientations: 'transverse', 'coronal', 'sagittal'. |
|
[-m
<mode>] |
Specifies the mode to be used at startup |
|
[-nosig] |
Display opens without functional image displayed. |
|
[-notool] |
Toolbar is not displayed. |
|
[-lstat
<positive float or int>] |
Starting display uses the indicated lower threshold
for display of functional image. |
|
[-hstat
<positive float or int>] |
Starting display uses the indicated upper
threshold for display of functional image. |
Keyboard shortcuts
Much of the toolbar functionality
can be accessed through keyboard shortcuts.
The shortcuts, listed below, are not case sensitive.
|
<Ctrl> T |
toggle display of toolbar |
|
<Ctrl>
A |
toggle functional display (+ and -, +, -, none) |
|
<Ctrl>
S |
save current image window as a .gif |
|
<Ctrl>
P |
print current image window |
|
<Ctrl> B |
toggle between continuous mouse-based coordinate
updating |
|
<Ctrl> W |
write information to FIV log. |
|
<Ctrl> R |
The Randy -- brings all FIV windows to the front. |
|
<Ctrl> L <series of numbers>
<return> |
set
lower activation threshold to specified value |
|
<Ctrl> H <series of numbers>
<return> |
set
upper activation threshold to specified value |
|
Right
arrow, left arrow |
increase, decrease brightness |
|
Up arrow, down arrow |
increase, decrease contrast |
|
Page
up or minus key |
scroll up in stack |
|
Page
down or equals key |
scroll down in stack |
|
Home |
move to first image in stack |
|
End |
move to last image in stack |
|
Tab
or space bar |
displays some useful information in a popup
window. |
Image and file formats
ImageJ expects the image
files to be 32-bit 4dfp stacks (typically with the .4dfp.img extension). It also expects to find corresponding header
files (with the .ifh extension). FIV can
handle images that have been transformed into 111, 222, or 333 space. The coordinates displayed in the toolbar
panel and popup windows will adjust automatically to the appropriate voxel size
as long as the header files are available.
If the header files are missing or corrupt, FIV will attempt to
determine an appropriate voxel size from the file name and file size, but
there’s no guarantee that the resulting coordinates and image display will be
correct.
Mind the memory
Be aware that MRI images tend
to require lots of memory to display.
And in order to optimize performance, every FIV display window that you
open contains a full-size copy of both the structural and functional
images. In order to keep users from
hogging resources, we’ve capped each running copy of FIV to use a maximum of
512 MB of memory. That’s plenty of
memory to open more than a dozen windows in 222 space, so most users will
seldom hit this cap. However, users who
wish to view images in 111 space may need to be more judicious with the number
of windows they have open at any given time.
Downloading
FIV can be downloaded and
installed on you local machine. The ‘FIV’ download contains all of the files
necessary to run FIV, including default images.
The ‘Sample Images’ download includes a number of functional and
anatomic images that may be of interest.
FIV (4.5 MB) Sample Images (23.6 MB)
Unintended features (i.e. bugs)
When FIV starts up, a bunch
of ‘font not found’ messages may show up in the command window. These can be safely ignored.
A good portion of ImageJ’s
functionality has been compromised to incorporate functional and anatomic
layers. Its shortcuts don’t work. It is aware of only the functional image (or
the structural image if no functional image is loaded.). Some of the ImageJ analyses may only operate
(including histrograms) on a portion of the image.
Default print settings are
set to black and white and portrait orientation. They must be set manually to black and white
and landscape.
Some alternatives
Hate FIV? Consider these alternatives…
Amide (http://amide.sourceforge.net/index.html)
MRIcro (http://www.psychology.nottingham.ac.uk/staff/cr1/mricro.html)
ImageJ (http://rsb.info.nih.gov/ij/)
IDOIMAGING (http://idoimaging.com/index.shtml)
– a portal to free imaging software
Dan
Marcus
Cognitive
Neuroscience Lab
Psychology
Department
April 29,
2005