BrainMaker Help

------------- Help for BrainMaker -------------
*** New Section ***

Summary of BrainMaker ROI Drawing Analysis Tool:

This program allows the user to draw ROIs on 3 orthogonal slices from an
image volume. A ROI drawn in one view is updated in the other two orthogonal
views. All functions and display aspects work equally well in all views.

You can then extract regional data from multiple slices of a coregistered
image volume to obtain information about an entire volume-of-interest (VOI).
You can also obtain morphometric information about individual VOIs.

The entire program is controlled through a series of Graphical User Interfaces
(GUIs) via the mouse. Little if any command-line typing is required.

There are also facilities for semi-automated region searches, image smoothing,
tissue segmentation, and numerous display options.

------------- Help for BrainMaker -------------
Introduction:

This routine and its subroutines allow the user to place Regions of
Interest (ROIs) on a MRI image volume, save the ROIs as a mask, and
apply the mask(s) to another image volume (e.g. PET) which has been
previously coregistered to the MRI volume. The MRI images act as a
reference for creating accurate delineations of 2D (slice) or 3D
(volumetric) anatomical structures. The ROIs from multiple slices are
combined to create a Volume-of-Interest (VOI) which is treated as a
single entity.
The philosophy underlying this program is that the bulk of the work in image-
analysis involves defining regions. This program seeks to make the process of
defining regions as rapid and accurate as possible, and also attempts to ensure
that the regions, once defined, can be stored and used later with confidence.

The ROIs are stored in an image-volume which has the identical dimensions as
the reference (MRI) volume. This can require a large amount of storage space,
but the possibility of error in extracting data for a masked area is minimized.
In addition, this format facilitates treating data from multiple slices
as a cohesive Volume-of-Interest, so values for all pixels within an
entire anatomical structure are weighted equally.

Coregistering related image volumes (e.g. PET) to the reference MRI
volume permits subsequent extraction of data for each ROI or VOI.
This program does NOT perform coregistration. The image volumes should
be coregistered PRIOR to using this program. You may use any
coregistration method you like, but it is up to you to verify the
validity of the coregistration for each data set. Some tools are
provided in BrainMaker to assist in this.

------------- Help for BrainMaker -------------
Getting Started: Overview

This section gives an overview of the steps required to start using
BrainMaker. Refer to subesequent sections for specific details.
If you are unfamiliar with BrainMaker, you should read all of
the "Getting Started" sections before proceeding.

0) Enter BrainMaker GUI environment from SPAMALIZE.
1) Read in a reference file. Typically this will be a MRI image volume.
Most buttons are de-activated until a valid MRI has been loaded.
2) Read in a coregistered image you are interested in (typically a PET file).
This step is not required, but it is helpful for comparison purposes.
3) Most drawing actions are controlled from the "ROI Draw Menu".
Pass the cursor over a button to obtain a brief description of its use
in the Draw Menu's message window. Click on a button to use it.
4) View different axial slices by selecting and dragging the slider
labeled "Axial Plane #", or by clicking on the nearby arrow buttons.
5) Obtain coronal and sagittal views by clicking the "Coronal orientation"
and "Sagittal orirntation" buttons.
6) Change location by clicking with the left or middle mouse button on any image.
The left mouse button is for drawing, the middle mouse button is for changing
location only. The right mouse button pops up a menu of shortcuts.
7) Obtain access to optional parameters by clicking "Display Options" button,
which pops up the "BrainMaker Display Parameters" menu if it is not present.
8) The "Anatomy" button pops up a menu which allows you to specify anatomic structures,
read or create a ROI mask volume, and provides tools for saving, deleting,
and viewing masks.
9) Click on the "Segmentation" button to get a large menu for segmenting the MRI
imge volume, using a histogram of the data. You can also smooth, find edges,
specify ROI drawing for specific tissue types, etc. from this menu.
10) There are many canned analysis procedures available in the "Analysis" menu.
For example, extract values from PET data for anatomical structure by clicking
on the Analysis menu item "Apply ROI".
11) Select "ROI stats" to see parameters for the current mask and location.

------------- Help for BrainMaker -------------
Getting Started: File Info

All image files used by BrainMaker must be in ANALYZE format (Mayo Clinic,
Rochester, MN), which consists of a block of data accompanied by a small
header file. You should be familiar with this format, or have a friendly
relationship with someone who is.

The user should have read-permission for the original MRI (and PET)
images, and write-permission for the directory where any output files
(like the ROI mask) will go. The default location for most output in
SPAMALIZE is to a directory on a large disk that all users have
write-permision for. However, the nams of the output ROI mask file is
based on the full name (including the path) of the MRI file, so the
output ROI mask file(s) are written to the directory where the original
image volume lives. Check with your local SPAMALIZE administrator if
you have trouble writing a file.

If you will create a ROI (mask) image, you will need to write to the
MRI directory. If you do not have write-permission to the directory
containing the MRI image, you should copy the MRI data file (.img) and
the MRI .hdr file to a directory which you own and can write to.

If you apply a ROI to a coregistered (PET) volume, the output generally
is placed in the PET directory. Many analysis routines allow you to
specify a file name and location. In all events, you must have
write-permission for the output directory.

------------- Help for BrainMaker -------------
Getting Started: Read MRI Reference

The first step is to read in a reference image volume which is in
ANALYZE-format. Typically this is a MRI file, but it can be any
ANALYZE-formatted image volume. The contents of the file are
irrelevant. It can be any of the following types:
BYTE 8-bit unsigned integer
INT 16-bit signed integer
LONG 32-bit signed integer
FLOAT 32-bit floating point
DOUBLE 64-bit floating point
The image volume should contain three (3) dimensions: X, Y, and Z. It
is possible to read a 2D or 4D volume, but many of the analysis and
display programs will balk. The convention is that the image data file
ends in ".img" and the header file ends in ".hdr". These files must be
in the same directory. When specifying a file, generally you need to
supply the full directory path as well as the file name.

To read a MRI volume, click the flashing file-folder icon next to the
MRI File text box. The icon flashes "Pick Me". Use the browser to
select an ANALYZE image. A good sample data set is contained in the
SPAMALIZE data directory. At the LfAN, this is:
/d2/pccommon/_terry/data/nT1.img
/d2/pccommon/_terry/data/nT1.hdr

Upon loading, the current location is the pixel designated in the
header as the "origin", or else the center of the volume.
The corresponding plane(s) will automatically be displayed.

File Display Conventions:
ANALYZE data are stored with the first point as the subjects
lower, back, right-hand side (inferior, posterior, right).
This means that the first plane in a data set is usually the
bottom-most. This also means that ANALYZE images are displayed
according to the RADIOLOGICAL convention, where the subjects RIGHT-HAND
side is displayed on the LEFT-HAND side of your screen (Right-is-Left).
Some programs (like SPM) will automatically swap the right- and
left-hand sides to obtain a Neurological view (Right-is-Right).
Results from different programs are compatible as long as:
a) no swapping occurs, or
b) the data are unswapped prior to writing to a file.

The bottom of the brain is usually toward the left of the slider,
the top of the brain is usually toward the right of the slider.
For non-standard ANALYZE files the orientation may be different.
YOU MUST CHECK THIS ASSUMPTION FOR ALL OF YOUR DATA!

------------- Help for BrainMaker -------------
Getting Started: Read PET Reference

You may load an image volume which has been coregistered to the MRI
reference volume. Typically this is a PET volume from which you wish
to extract ROI information. Note that the PET data is not actually
used for anything during the process of creating the ROI masks. There
is no need to load the PET data, but it can be helpful in some cases to
compare the physiological and structural information.

The PET image (if loaded) is displayed in the "Adjunct" display
window. If you choose not to load a PET image, the MRI and/or mask
will be displayed in this window instead. This can lead to the
appearance of redundancy, but this window is useful if you load a PET
image.

The PET data must be in an ANALYZE-formatted file. If the PET file
does not have the same dimensions as the reference (MRI) SPAMALIZE will
refuse to read in the PET file. Click the file-folder icon next to the
"PET File" text box.

The image displayed in the Adjunct window is determined by the
"Orientaion" icons. To view a coronal slice in the Adjunct window,
click on the "Coronal orientation" icon. To make the Adjunct window
disappear (and speed up display slightly in other windows), click on
its "Quit" button. It wil only re-appear when you click the "Show
Adjunct View" button.

Clicking in the Adjunct view will cause a connected-pixel search to be
performed starting in that location, but based on the MRI image.

------------- Help for BrainMaker -------------
Getting Started: Draw ROI Intro

In this program, when you draw a Region-of-Interest (ROI) you are actually
creating a binary mask of a region. Conceptually, all pixels within the ROI
have a value of "1" and all other pixels in the mask-image have a value of zero.
There are many ways to draw a ROI:
1) Draw around the edge of a structure using the ROI freehand tool;
2) Use a shape-tool (circle, rectangle, etc.) to draw a specific shape;
3) Add/remove a pixel (or group of pixels) using the pencil/eraser tool;
4) Find similarly-valued pixels spatially connected to the current pixel;
5) Fill interior regions of a partially drawn ROI;
6) Use the tissue segmentation information to limit a ROI to a range
of values.
The mask produced by any of these approaches is treated identically once it
is created.

Drawing a structure freehand is generally the most reliable and
time-consuming approach. It is the only option if the structure does
not have crisp edges, or if there is a small path that allows the
search to "leak" into unwanted areas. Select the "Draw ROI (freehand)"
button. Click the left mouse button in a draw-window to start the ROI,
and release the button to close the ROI.

You can edit individual pixels, or groups of pixels, by using the
pencil and eraser icons. Select a cursor size by clicking on one of the
"Cursor size..." icons. The "Smart Add/Remove" feature will add to the
mask if the current location is NOT in the mask, and will delete from
the mask if the current location IS in the mask. Editing individual
pixels is extremely useful, but will "hiccup" frequently: the program
will not notice that you pressed a button about 10% of the time. This
is frustrating, and happens because the program is processing a huge
amount of data and ignores button events until it is ready to start a
new process.

To perform a connect-pixel search from the current pixel location,
click on the bloodhound icon. A connected-pixel search works well if
the structure is well-defined with crisp edges. A thresholding
technique is used which finds all pixels which:
a) are spatially connected to the selected pixel, and
b) have a value which is close to the value of the selected pixel.
The "Threshold" slider in the "BrainMaker Display Parameters" menu
determines the criteria for how close the value must be.
Acceptable values must lie within a band defined by:
(original value) +/- ((original value)*(threshold/100))
Typical threshold values to define selected structures are:
STRUCTURE THRESHOLD
whole brain 20
cerebellum 12
putamen 2-5
Note that the smaller the threshold value must be to exclude unwanted
pixels, the less likely it will be that this approach will work.

------------- Help for BrainMaker -------------
Getting Started: Draw ROI Buttons

Other buttons in the ROI Draw Menu are:
- Draw ROI-Inverse: A region is drawn in the same manner as the normal
"Draw ROI", but the resulting region is EXCLUDED from the current
working mask, instead of included.
- Zap connected pixels: finds all mask pixels connected to the
current pixel (if any) and removes them from the mask.
- Fill ROI: paints vertical, horizontal lines to fill interior holes.
- Fill ROI (vertical): only paints vertical lines.
- Nudge Up/Down/Left/Right: These buttons nudge the entire 3D VOI in
the desired direction, according to the current view. For instance,
moving the VOI "up" in the axial view moves the VOI toward the front
of the brain; moving the VOI "up" in the sagittal view moves the VOI
toward the top of the brain.
- Flip mask: reverses X-coordinates, to flip the mask about the cantral
sagittal plane.
- Mask toggle: The left mask represents the 3 orthogonal views, the right
mask represents the adjunct view. The mask can be displayed as an outline
(default), solid fill, or none. New choices don't take effect until a new
display is requested. For outline mode, the lines are OUTSIDE of the ROI,
which means the entire ROI is visible inside the outline. The most reliable
way to see a mask is in "Fill" mode.
- Refresh mask: sets the entire working mask to 0. Do not use this feature
if you intend to save your work later- it will be gone and you will have to
start over. However, in early stages of drawing it is very convenient.
- Cut: Deletes mask from current view-plane only, and places it in "clipboard".
- Copy: Copies mask from current view-plane only, and places it in "clipboard".
- Paste: Overlays clipboard contents onto current view-plane.

At this point the mask is a temporary working image. You may edit the
mask by adding or removing pixels. Changes are cumulative. There is no
ability to return to the previous step (undo) if you are unhappy with a
change, but you can add or remove pixels at any time. To start over,
select "Refresh mask", which sets all pixels in the working mask to
zero.

Put the current working mask into the reference mask-volume by
selecting "Store ROI" in the Anatomy menu. Note that this only stores
the mask to an array in memory. To save the entire reference mask
volume to the file, select "Save ROIs to File" from the Anatomy menu.

------------- Help for BrainMaker -------------
Sub-Menus

This section describes features available through various sub-menus.

Display Options: Pops up a separate window with numerous options and
parameters. The current location is shown here. You can type a
number into any of the location test-boxes to go to that location.

Anatomy: Pops up a separate menu that allows you to specify anatomical regions.
This menu is where you load an existing mask or create a new one,
save or delete a ROI from the mask, name the ROI, save the mask volume
to a file, and examine ROIs. This menu has its own "Help" menu.
This is not really a sub-menu, but rather is just as important as
the main BrainMaker menu.

Segmentation: Pops up a menu for image segemntation (tissue classification).
The segmentation is based on a histogram of the MRI data. There are
sub-menus to smooth the MRI volume, find edges, etc.

ROI stats: Pops up a separate menu that displays statistical information about
the currently loaded image volumes (MRI, PET, Mask) as well as for the
current ROI.

Analysis: Produces a pull-down menu with a number of analysis options.
The underlying programs tend to be in a state of flux. All programs have
worked (and worked well) in the past. If you experience difficulties,
notify Terry Oakes; it will probably take only a minor tweak to fix things.

Help: Produces a pull-down menu with a number of Help topics.
This was how you got here.

Quit: Quits from ROI analysis tool, deleting the main window and all sub-windows.
If you quit, you will have to start all over again by loading in new images.
You will lose any data not explicitly saved to a file. If you have an unsaved
ROI mask, BrainMaker should prompt you to save it before letting you quit.
Quitting is a good way to start over; however, SPAMALIZE keeps the MRI volume
in memory, and BrainMaker will re-load the MRI volume if you renter it
without quitting from SPAMALIZE.

------------- Help for BrainMaker -------------
Drawing Hints

Filling in a Mask
The "Vertical Fill" option (Button "Fill-V") complements the "Convex fill"
option (Button "Fill"). Vertical fill only fills in vertical columns.
This works well for filling a region from the bottom portion of the brain,
where the frontal lobes protrude from the brain. Convex fill tends to fill
the region between the lobes, which frequently contains unwanted tissue.

Tools to examine validity of a coregistration.
"Interleaving" creates an image where all even rows are PET, all odd rows are MRI,
so user can see both images together. Use a threshold value of ~60%.
"Overlaying" finds the edges of structures in the MRI image, and superimposes
these edges onto the PET image. A threshold value of ~90% works well for the
threshold method, a threshold value of ~0% or more usually ~30% works well for
the windowed method.

------------- Help for BrainMaker -------------
Anatomic Masks

Select the "Anatomy" button from BrainMaker's main menu. The resulting
pop-up menu provides facilities to name the current ROI, display a
specific ROI stored in a file, write a ROI to the file, or delete a ROI
from the file. This routine depends on an environment provided by
SPW_ANLZ_ANAT.

There are currently ~30 named anatomic regions defined. Additional
regions may be defined by editing the file SPAM_ANAT_DEF.PRO, which
contains instructions for adding a new region.

This menu contains its own "Help" menu, which explains the concepts
and use of the various mask volumes used by BrainMaker.

------------- Help for BrainMaker -------------
Create ROI Mask

There are three mask volumes you need to know about:
1) working volume: Contains a single ROI volume (VOI),
which is the volume you create and edit in the view-windows.
2) reference volume: Contains one or more distinct VOIs.
The reference volume exists in memory (not on disk) and
is a container for individual VOIs.
3) ROI mask file: A semi-permanent copy of the reference volume.
You should save the reference volume to the file when you are done,
or if you have a feeling of impending doom. I call it semi-permanent
because it is possible to change its contents, but at the end of the
day this is where your ROI/VOI work gets saved.

You must create a mask-file before you can save the ROIs you will draw.
You may add ROIs to a previously existing mask-file (i.e. one that you created
in a previous session).

To create a new mask-file, select "Create File". The default naming convention
is to add "ROImask" to the reference filename. If you follow this naming convention
then subsequent searches, etc. will be facilitated. You must have write-permission
for the disk (folder) where you wish to store the new mask-file. An ANALYZE file
with the identical dimensions as the reference file (MRI) will be created.

To load an existing mask-file select "Find File". There is some error-checking
to ensure that the mask-file has the same dimensions as the currently loaded
reference file (as described in the associated .hdr file). However, it is up to
the user to ensure that the mask-file is related to the reference file, and also
that any coregistered images are related (i.e. from the same subject).

This program does NOT check to see that image-volumes are from the same subject.
This provides maximal flexibility, but also requires the user to take some
responsibility for his/her data.

------------- Help for BrainMaker -------------
Store ROI

There are four steps to saving a mask for a region:
1) Create the mask (working version).
2) Select a name for the region from the Anatomy menu.
3) Store the masked pixels in the working version of the mask volume
to the reference version (in memory).
4) Write the reference mask volume to the mask-file.

Step (1) is reviewed in other Help menus. The most important step is to define
what the region will be called, which in turn determines how it is stored.

To select a name, simply select an item from the Anatomy menu. You may select
either "Right", "Left", or "Both" for any named structure. To unselect a structure,
select the "None" button. You may only store a mask for a single structure at a
time. If more than one structure is selected, SPAM_WRITE_ROI_MASK will refuse
to store anything, and will print a message to the screen informing you of
the nature of the conflict. Click "Unselect All" to unselect all structures,
then select the single structure you wish to write.

If you draw a region and store the mask, then draw another region without selecting
a new mask-name, you will create the "AND" of the two regions, with the label
of the first region. This can be helpful at times (e.g. to create a mask composed
of isolated islands of tissue) but is generally regarded as a mistake. You will
be unable to separate the mask into its Right and Left components.

If the new ROI includes pixels previously drawn in another ROI, these pixels will
no longer belong to the old ROI. The pixels will not be lost to the old ROI if
the new ROI is a child (subset) of the old ROI. For instance, most regions are
subsets of "whole_brain" and "left_brain" or "right_brain".

Every structure defined in the Anatomy menu has a unique integer value associated
with it. (To determine the actual values, see the comments in SPW_BRAIN_ANAT.PRO).
Furthermore, left-side structures have positive values, and right-side structures
have negative values. Searches for an entire structure can easily be performed by
looking for the absolute value of the desired structures value.

Nested structures can be accommodated. For example, the caudate and the putamen
constitute the striatum. The cuadate has a value of "51", the putamen has a value
of "52". The structure defined by "striatum" contains the subgroups "caudate" and
"putamen", so values of "51" and "52" correspond to the striatum.
Note that although the striatum has a value of "50", this value is never stored.
The user should only write masks for atomic structures.

To permanently save your work, you must write it to a file. First you must create a
new ROI file, or load an existing one (reviewed elsewhere). Selecting "Save ROIs to
File" will save your work. This will cause the current contents of the reference
ROI mask volume (in memory) to be written out to the file named in the Anatomy menu.
Note that this will overwrite the existing contents (if any) of this file.
You can avoid this by renaming the file in the Anatomy window. For example,
rename "/data2/p123_ROImask.img" to "/data2/p123_ROImask_new.img".

The working ROI volume will persist in memory until:
- you load in a new ROI mask file;
- you quit the ROI draw program;
- SPAMALIZE crashes.

------------- Help for BrainMaker -------------
Delete ROI

Deleting a region from a mask-file is a three-part process:
1) Select the region you wish to delete from the mask-file.
2) Determine what to name the ensuing "hole" created in the mask-file.
3) Delete the region.

The major issue in deleting a region is that it may overlay another region.
For instance, most structures lie within the larger region "whole brain".
The procedure used by this program allows the user to specify any region,
including "Undefined", to replace the void created when a region is deleted.

Select "Delete ROI" from the Anatomy menu. A special menu appears with a window.
Move the cursor over the image until the desired structure name appears in the
text-box. Follow the printed instructions (click the mouse button) to select
the structure you wish to fill in the void which will be created when the current
region is deleted. To fill with a region which does not exist (because you have
not drawn it) you can type in the name of a valid region. This is for advanced
users only! You can also select (or type) "Undefined".

You must "Quit" from the delete menu before proceeding to draw another ROI.

------------- Help for BrainMaker -------------
Ghost Removal

This program was designed to remove "Ghost artefacts"
from a MRI image volume, but is fairly general-purpose.
It will set all pixels in a group of axial planes to 0.

To select a group of planes, move within BrainMaker to the
first (last) axial plane you want to set to 0. All planes
between this plane and the top (bottom) of the image volume
will be set to 0.

If you are above the middle plane, all planes from the current
to the top plane will be set to 0. If you are below the middle
plane, all planes from the first to the current plane will be set
to 0.

The result will be written to a file named something like:
/full_path/mri_filename/ug.im
The "_ug" suffix stands for "unghosted".

You can remove both top and bottom planes in succesion, and have a
single file in the end.

------------- Help for BrainMaker -------------
Find Brain

This routine is designed to strip away non-brain pixels outside of the
brain itself. It tends to err on the side of including all of the brain,
at the expense of also including some non-brain pixels. This balance
can be easily shifted by editing the program.

The program is controlled from within the BrainSegmentation menu.
To use it, put the CSF/GM threshold at the uppermost value for CSF,
and put the WM/Top threshold near (but somewhat less than) the upper
value for WM.

------------- Help for BrainMaker -------------
These are the subroutines you must have available to run SPW_ANLZ_ROI:
SPAM_ANLZ_ROI_HELP
UPDATE_LOAD_ANLZ_ROI
RESIZE_DISP_ANLZ_ROI
UPDATE_FILENAME_SIZE
UPDATE_IMGS_DISPLAY
SPAM_OUTLINE
UPDATE_ORTHO_VIEWS
UPDATE_CURSOR_LOC
UPDATE_FILENAME_SIZE
UPDATE_CROSSHAIRS
SPW_ANLZ_ANAT
SPW_GUAGE,SPAM_GUAGE
SPW_ANLZ_ROI_DEL
SPAM_SAVE_ROIMASK
SPW_ANLZ_ROI_PARAMS
RESIZE_DISP_ANLZ_ROI
UPDATE_INFO_WIDG
SPW_ANLZ_ROI_ORTHO
UPDATE_ORTHO_VIEWS
SPAM_READ_ANLZ
create_anlz_hdr()
SPAM_PROF
SPAM_ROI_DRAW
SPAM_BRAIN_ROI_APPL
SPAM_ANLZ_EXTRACT_ROI
SPAM_ANAT_DEF
SPW_ANLZ_ROI
SPAM_READ_ANLZ
SPAM_WRT_ANLZ
SPAM_ANLZ_ROI_RATIO
SPAM_ANLZ_EXTRACT_ROI
SPAM_ANLZ_EXTRACT_ROI
SPAM_PATLAK

Back to BrainMaker