README

CVCNS Surface Constructor README

Last Updated: $Date: 2007/05/07 12:51:07 $
Latest Version: 0.15

The Surface Constructor (surfCon) is an application aiding in the
production of two-dimensional triangular mesh surface representations
of the boundary of three-dimensional objects. Input to surfCon is a
set of images of serial volume slices through an object. The images
are first mutually aligned if necessary, then points on the boundary
of the object are identified. The output of surfCon is a mesh
representation of the surface of the object. The Surface Constructor
is appropriate for use with partial surfaces, open surfaces, and
closed surfaces.

This README describes how to use surfCon, with which it is
distributed.

__________________________________________________________________________

CONTENTS:

 (1) INTRODUCTION

 (2) SURFACE CONSTRUCTION OVERVIEW

 (3) ALIGN MODE

 (4) CONTOUR TRACING MODE

 (5) SURFACE RECONSTRUCTION

__________________________________________________________________________


__________________________________________________________________________

(1) INTRODUCTION

surfCon is intended for use in neuroscientific experiments where the
reconstruction of the brain surface from imaging data is desired.

Having a surface representation of the brain is desirable for
visualization purposes. Functional data can be mapped directly onto
the brain surface, allowing careful examination of the data in a
context similar to the intact brain. Also, portions of the brain
surface can be flattened into two dimensions, allowing the viewing of
regions of brain data normally hidden in sulci and allowing comparison
of flattened regions among a group of subjects.

surfCon may have uses outside of brain surface
reconstruction. However, the design and implementation of surfCon have
focused on solving the brain surface construction problem. Therefore,
if you are using the program for something else, be warned that it may
not work, but we would still like to hear about your experience.

Questions and comments can be directed to Oliver Hinds <oph@cns.bu.edu>.

__________________________________________________________________________


(2) SURFACE CONSTRUCTION OVERVIEW

To reconstruct a brain surface, appropriate imaging data is necessary.
This data can be obtained from serial brain sections prepared in
slides and scanned into a computer, MRI images, or any other technique
that results in a set of computerized images of parallel slices
through the brain at known intervals.

Brain surface construction can be viewed as four conceptually separate
tasks. The brain slice images must be mutually aligned, points of
interest such as electrode lesions must be marked, the surface of the
brain must be traced on each slice image, and the brain mesh must be
generated from the traced contours. After this process is complete,
the brain surface can be visualized in a variety of ways, including
tools such as MATLAB, Geomview, VTK, and others.

The process of surface construction is partly manual and partly
automatic. The manual portions of the process include aligning the
slice images, marking locations such as electrode lesions on the slice
images, tracing contours representing the surface of the brain, and
correcting the connectivity of the slice contours in adjacent slices
guessed at by surfCon. Automatic portions of the surface
reconstruction process include the initial guess at contour
connectivity, solution of contour branching conditions, and generation
of a surface mesh from the input contours.


APPLICATION EXECUTION

The process of executing surfCon will be described with
a short tutorial. Full documentation for the algorithmic underpinnings
can be found within the SurfaceReconstructionLibrary and
VolumeProcessingLibrary subdirectories.


THE DATASET

surfCon operates on a "dataset". The term "dataset" is used to refer
to all the information, data, and files needed or generated by surfCon
in the process of constructing the surface representation of one
brain. A dataset has associated with it a set of slice images, each of
which has a set of contours: points representing the surface of the
brain to be reconstructed. A dataset is stored in a text file, called
a dataset file, containing information needed by surfCon. The saving
of the dataset file allows you to work on the same dataset over
multiple sessions.

The current dataset file can be saved at any time during the execution
of surfCon by pressing the 's' key on the keyboard
or by choosing the 'save' option from the right-click contextual menu.


INITIALIZING THE DATASET

On the first execution of surfCon for a dataset, the dataset file
associated with a desired brain surface is created. surfCon needs
several pieces of information in order to build this file. This
information will be stored in the dataset file for automatic loading
upon subsequent execution. Therefore, this information only needs to
be specified once.

surfCon can load slice images from JPEG, DICOM, or PNM (PPM) image
files, or a volume from an MGH volume file. If image files are being
read, the locations and ordering of the slice images must be specified
in a list on the command line the first time the dataset is
loaded. Examples of creating a dataset from images or volumes are
given below.

A New Dataset From Image Files: 
-------------------------------

Initial Required flags:
   -c : signal dataset creation
   -f : dataset filename
   -d : directory the slice images are stored relative to the current directory
   -n : number of slice images in the dataset
   -i : image format (ie: jpeg)
   -s : size of a pixel in each dimension (in millimeters)

Execute surfCon with the initial required flags and the
ordered list of slice image names from the demo directory:

	surfCon -c -f image_demo.ds -d . -i jpeg -n 4 -s 0.1,0.1,2 0000.jpg 0001.jpg 0002.jpg 0003.jpg

This tells surfCon that it will create a new dataset ('-c'), that this
dataset will be stored in the file 'image_demo.ds' ('-f'), that the
slice images are located in the current directory '.' ('-d'), that
there are four slice images ('-n') of type jpeg (-i), and that each
slice image has pixels that are 0.1mm X 0.1mm with each image spaced
2mm from the next (-s). The slice images are then listed in the order
on the end of the command line.

Alternatively, a file containing a list of the slice file names may be
specified on the command line using the '-l' flag. For example, the
following command has the same effect as the command described above:

	surfCon -c -f image_demo.ds -d -n 4 -i jpeg -s 0.1,0.1,2 -l demofiles.txt

where the file 'demofiles.txt' consists of the lines:

0000.jpg
0001.jpg
0002.jpg
0003.jpg

Also, a file containing a list of the positions (in the z dimension)
of each slice may be specified on the command line using the '-z'
flag. For example, see the following command:

	surfCon -c -f image_demo.ds -d . -n 4 -i jpeg -s 0.1,0.1,0.4 -z slice_pos.txt -l demofiles.txt -i jpg

where, for example the file 'slice_pos.txt' consists of the lines:

0.001
0.015
0.020
0.035

which represent the z position of the slices in millimeters.


Each subsequent session using the same dataset requires specification of
the dataset file only. So to load the dataset created above again, just
execute:

	surfCon -f image_demo.ds

from the same directory.


A New Dataset From A Volume File: 
-------------------------------

Note: this example doesn't exist in the demo directory, so you'll have
to provide your own MGH file.

Initial Required flags:
   -c : signal dataset creation
   -f : dataset filename
   -v : the MGH format volume filename to read

Execute surfCon with the initial required flags 

	surfCon -c -f vol_demo.ds -v vol_demo.mgh

This tells surfCon that it will create a new dataset
('-c'), that this dataset will be stored in the file 'vol_demo.ds' ('-f'),
that the volume file containing the slice images should be loaded form
the MGH volume file 'vol_demo.mgh' (-v).

Each subsequent session using the same dataset requires specification of
the dataset file only. So to load the dataset created above again, just
execute:

	surfCon -f vol_demo.ds

from the same directory.


GENERAL OPERATION

To view the list of allowable actions and commands at any point during
the execution of surfCon, click the right mouse
button. This will present a drop-down contextual menu with several
options. Actions that are global to surfCon such as 'save',
'quit', and mode switching are located at the top of the menu, while
mode specific options are located lower in the menu.


MODES OF OPERATION

There are two modes of operation of surfCon: Align
Mode and Trace Mode. Align Mode allows the mutual alignment of the
slice images by translating, rotating and scaling the images with
respect to one another. Trace Mode allows the identification of
landmarks such as electrode lesions on the slices, as well as the
tracing of contours representing the surface of the brain to be
reconstructed.

Modes can be selected from the drop-down contextual menu at any time
during execution of surfCon. Also, Align Mode can be
entered at any time by pressing the 'A' key inside the surfCon
window, while Trace Mode is entered by pressing the 'T' key inside the
window.

GLOBAL COMMANDS

The following is a list of options available in both ALIGN and TRACE
modes:

Navigate among slices:
  ',' or '<' : move one slice down
  '.' or '>' : move one slice up

Zoom in
  'i'

Zoom out
  'o'

Decrease the brightness of the display
  ';'

Increase the brightness of the display
  '''

Decrease the contrast of the display
  '['

Increase the contrast of the display
  ']'

Build a correspondence guess
  '/'

Construct the surface
  'z'

Save the dataset file 
  's'

Switch the slice direction (if a volume file was read)
  'h'

Documentation for the operations allowed in each mode are documented
in the following two sections.

__________________________________________________________________________



__________________________________________________________________________

(3) ALIGN MODE

Access Align Mode by pressing 'A' (note capitalization!) at any time
within surfCon window.

To construct a surface from serial sections, each section must be
aligned to adjacent sections. surfCon provides a
mode of operation that allows translation, rotation, and scaling of
one slice (the "movable slice") with respect to the previous slice
(the "reference slice"). During alignment, the name of the slice being
aligned is displayed in the top left corner of the window.

Once surfCon window is in view, press the 'A' key to
enter Align Mode. You will be presented with the first slice image.
Using the left mouse button, click, hold and drag the slice image such
that the relevant brain section is centered in the window. The
alignment of this first slice image is important because all further
images are aligned with respect to it. Therefore, try to place this
image in a location that will allow subsequent brain images to be
located near the center of the screen.

It may also help to rotate the first slice image with respect to the
application window. Notice the red dot in the center of the screen.
This is the rotation center, meaning that any rotations of the image
will be centered on this point. The rotation center can be moved to
any place in the window by first selecting 'set rotation center' from
the drop-down contextual menu (or alternatively press the 'c' key)
then clicking at any location in surfCon window. The rotation
center will then be set.

To rotate the image, use the middle mouse button to click, hold and
move the mouse. The image will rotate around the specified rotation
center.

Both translation and rotation can be made less sensitive to mouse
movement by holding the 'Ctrl' key while translating or rotating the
image. This is referred to as "fine translation" or "fine rotation".

Once the first image has been aligned, move on to the next slice image
by pressing the '.' key (or by selecting the 'increase current slice'
option from the drop-down menu). You will then be presented with an
alternating view of the first (reference) and second (movable) slices,
flickering quite fast. Although both slices are visible, only the
second slice is movable. The idea is to align the second image as well
as possible to the first. Using the left mouse button, translate the
second slice such that one easily recognizable point near the center
of the images is in register with the corresponding point on the first
image. A well defined apex of a gyrus or the trough of a sulcus is
usually a good choice.

Once the correspondence of one point on both images has been made, set
the rotation center to that point as described above. Next, rotate the
second image with respect to the first until the images are in as
close alignment as possible. This is a good rough alignment, which
should be refined using the fine translation and rotation tools as
described above. Also note that the flicker speed should be decreased
for fine alignment. There is a "locking" effect that occurs when the
images are in alignment that is more pronounced when the images are
flickering at a lower temporal frequency than the default. Change the
flicker frequency of the two images by using the menu options from the
drop-down menu, or by pressing the 't' key to slow down the flicker,
and the 'y' key to speed it up.

The flicker can also be stopped altogether by pressing the 'a' key, or
by selecting the 'toggle animation' option from the drop-down menu.
Stopping the flickering can help with fine alignment, with determining
the location of a hard-to-see part of the movable image with respect
to the reference image, and can be helpful when quickly cycling
through the images as a sort of "fly-through" of the slices to
determine overall quality of the alignment.

Repeat the above described procedure for each slice, navigating
through the slices with the ',' and '.' keys. As always make sure to
frequently save the dataset using the 's' key or the option from the
drop-down menu. A complete description of all operations for Align
Mode are listed below.


OPERATIONS
(all commands are accessible from the drop-down menu via the right button)

Translation of the movable slice with respect to the reference slice:
  coarse : left mouse button
  fine   : numeric keypad (with numlock on) or the left mouse button with 'Ctrl' key

Rotation of the movable slice with respect to the reference slice:
  coarse : middle mouse button
  fine   : middle mouse button with 'Ctrl' key

Move the center of rotation
  'c' followed by the left mouse button

Scale the movable slice up with respect to the reference slice
  '+' or '='

Scale the movable slice down with respect to the reference slice
  '-' or '_'

Toggle the image switching animation (go from seeing one image at a
time to seeing both switch, or vice versa)
  'a'

Decrease the image switching speed
  't'

Increase the image switching speed
  'y'

Toggle viewing of contours on previous slice
  'e'

Toggle viewing of contours on current slice
  'w'

__________________________________________________________________________


__________________________________________________________________________

(4) CONTOUR TRACING MODE (AND MARKER PLACEMENT)

Trace Mode can be entered by pressing the 'T' (note capitalization!)
key at any time in surfCon window.

For a brain surface to be extracted from sections, surface contours
representing connected components of the brain surface to be
constructed must be identified in each section. surfCon provides a
mode for tracing and modifying contours through the placement of
"tacks" along the brain surface. An implicit linear interpolation
between tack points in a contour represents the two-dimensional cross
section of the brain surface that will be used in the construction.


LANDMARK IDENTIFICATION

For many applications it is important to be able to identify certain
points of interest such as electrode track locations. surfCon allows
the identification of these points by placing special 'markers' on
them.

To place a marker, hold the 'Shift' key and click the left mouse
button. After a marker has been placed, it can be moved by clicking,
holding, and moving the mouse with the left mouse button depressed.
Markers can be deleted by clicking on them with the middle mouse
button.

Place a few markers on the first slice in the demo. You will see that
markers are displayed in an orange color, changing to a green color
when they are being moved. Delete a marker using the middle button as
described above, and replace it with the left button.

Use the '.' key to go to the next slice image. Place a few markers
here, too. Press the 'e' key (or select 'toggle left contour
visibility' in the drop-down menu). You will see the markers just
placed on the previous slice drawn in a lighter orange color.

Again, use the '.' key to go to the next slice image. Place a few
markers. Go back to the previous slice by pressing the ',' key. Press
the 'r' key (or select 'toggle right contour visibility' in the
drop-down menu). You will see the markers just placed on the next
slice drawn in a darker orange color.

Remember to save often using the 's' key or the 'save' option from the
drop-down menu. Next we will go over the tracing of contours.


CONTOUR TRACING

The main function of the contour tracing mode is to identify contours
that represent the desired brain surface. To accomplish this, tacks
should be placed along the image corresponding to points on the brain
surface. Begin tracing image slices by pressing 'T' to enter Trace
Mode, and making sure that the first image is being traced by ensuring
that the text in the top-left corner of the screen reads "slice N
trace:". If not, use the ',' and '.' keys to navigate to the first
slice image.

To trace a contour corresponding to one connected component of brain
surface in a slice image, place a series of tacks along the surface in
the image. To place a tack, click on the desired location with the
left mouse button. A circle will appear at the tack location. Place
another tack, and the previous and current tacks will be connected
with a line. This line is the implicit linear interpolation between
tack points that is the assumed two-dimensional intersection of the
brain surface with the slice image plane. 

Tacks can also be placed by dragging the mouse with the 'alt' key
pressed. This will place tacks every so often as the mouse is
dragged. Tacks are not placed right on top of one another if you stop
dragging. This method is preferable to clicking each individual point
if many slices are being traced.

Trace out one connected component by placing tacks all along the
visible portion of the brain surface in a continuous line. Depending
on the amount of curvature in the brain surface, the density of tacks
will be higher in some portions of the contour to keep the
interpolation line within the desired brain surface.

Delete tacks after they have been placed by selecting the tack to be
deleted with the middle mouse button. Multiple tacks can be deleted at
once by clicking and dragging the middle mouse button to define a
region within which all tacks in the selected contour will be deleted.

Because of the folding of the brain surface, there will be multiple
connected components of the brain surface in some of the slice images.
surfCon provides a method for identifying these
multiple connected components on the same slice. At any time a new
contour can be added in Trace Mode by pressing the 'n' key.

Once one contour for one connected component has been identified, use
the 'n' key (or the 'new contour' option in the drop-down menu) to
create a new contour. The first contour will change color to let you
know it is no longer being edited. New tacks now appear in a different
color, and the new contour is not connected to the old one with the
interpolation line. Trace the entire connected component, and repeat
this process for each connected component.

Use the '.' key to advance the slice image. The same procedure
described above is used to trace the contours on this slice image. To
make sure that the correspondence between the tacks for the previous
slice and the current slice is good, turn on the viewing of the
previous slice contours by using the 'e' key or using the 'toggle left
contour visibility' option in the drop-down-menu. The contours from
the previous image will appear in a light gray color.

Continue this procedure for all subsequent slices. Make sure to go
back one slice at time and view the agreement across three slice
images by turning on the left and right slice contours using the 'e'
and 'r' keys, respectively. Also make sure to save often using the 's'
key or the 'save' option from the drop-down menu. 

When all desired contours have been traced, correspondence between
contours on adjacent contours must be established before the surface
can bee constructed. To make an initial guess at the contour
correspondence, press the '/' key, or choose the 'build correspondence
guess' function from the drop-down-menu. 

The correspondence guess will almost certainly be wrong in some or
many cases. To manually edit the correspondence guess, there is a
submode of the trace mode that allows the adding and deleting of
contour correspondences. To enter the contour connection sub-mode,
press the 't' key while in Trace Mode, and the mode string at the top
of the window will read 'slice N trace (connecting contours):'. The
tacks in the contours of the adjacent slices will be visible. Placing
or deleting new tacks is not possible in this sub-mode.

Start from the beginning of the traced slices and cycle through each
contour on each slice, checking that those and only those contour on
the adjacent slice that should be connected to the current contour in
fact are. Contour connection is indicated by showing the adjacent
contour's vertices in full color, rather than the dark gray color
unconnected contours are shown in.

Contour connectivity can be modified in this sub-mode. To add a new
connection to the current contour, click with the left mouse button on
any of the vertices in the contour to be connected to the current
contour. Adjacent contours can be disconnected from the current
contour by clicking any of that contour's vertices with the middle
mouse button.

Once contour connectivity has been properly established, construct a
surface by pressing the 'z' key, or selecting the 'construct surface'
option from the drop-don-menu.


Tips for Tracing Contours
-------------------------

When contours are traced, there are a few tricks to use that will help
to ensure that the surfaces produced by the surface reconstruction
algorithm will be high quality. 

1) Make sure that there are no intersecting contour
segments. Intersecting contour segments are tested for when the
dataset is saved. If intersecting segments are found, the alert string
indicates this, and the end points of intersecting segments are
selected. Correct the intersections for a higher quality surface. 

2) Break up complicated branching situations. In cases where there are
multiple contours connected that join into a single contour on an
adjacent slice and these contours are arranged such that one contour
is "divided" by another contour, the "divided" contour should be split
so that all contour vertices that connect to contiguous section of
the single adjacent contour are contiguous. 


Below is a complete listing of the operations in Trace Mode.


OPERATIONS
(all commands are accessible from the drop-down menu via the right button)

Add a new contour to the current slice
  'n' or 'N'

Toggle line viewing
  'L'

Toggle contour closure state
  'c'

Toggle contour connection sub-mode
  't'

Break the current contour into two contours between the two selected neighbors
  'k'

Cycle backward through contours for editing
  'b'

Cycle forward through contours for editing
  'v'

Toggle viewing of contours on previous slice
  'e'

Toggle viewing of contours on current slice
  'w'

Toggle viewing of contours on next slice
  'r'

Place a new tack
  left mouse button

Place a new marker
  left mouse button with the 'Shift' key depressed

Select multiple tacks or markers
  click and drag the left mouse button with 'control' pressed over the
  tacks to be selected

Select single a tack or marker
  click the left mouse button over the desired tack or marker

Move a tack or marker
  click and hold the left mouse button on the tack and drag the mouse

Delete multiple tacks
  click and drag the middle mouse button over the tacks to be deleted

Delete a single tack or marker
  click over the tack with the middle mouse button

Insert a new tack between two existing tacks
  select two neighbors by clicking the left mouse button over each
  with 'Ctrl' key depressed, then place the new tack with the left
  mouse button

Scroll the window
  numeric keypad (with numlock on)

Increase the rate of automated tack placement
  'f'

Decrease the rate of automated tack placement
  'g'

Reverse the direction of the current contour
  'x'

Label the selected vertices on the current slice
  'l'

Select all tacks on the current slice
  'a'

Unselect all tacks on the current contour
  'u'

Unselect all tacks on the current slice
  'U'

Build a guess at contour correspondence
  '/'

Clear all contour correspondences
  '?'

__________________________________________________________________________


__________________________________________________________________________

(5) SURFACE CONSTRUCTION

After all contours have been identified, the surface is constructed by
executing the surface construction algorithm. The algorithm is
executed by pressing the 'z' key in any mode. The result of the
surface reconstruction algorithm is a surface saved in the OBJ file
format with the same name as the dataset file with '_surf.obj'
appended to the dataset filename. A vertex label file is also
written. This file has the same name as the surface OFF file, with
'.lab' appended to the name.

__________________________________________________________________________

email questions or comments to oliver hinds <oph@cns.bu.edu>
$Id: README,v 1.32 2007/05/07 12:51:07 oph Exp $

 LocalWords:  CVCNS README surfCon neuroscientific MRI MATLAB Geomview JPEG VTK
 LocalWords:  PNM PPM MGH jpg demofiles txt pos Ctrl gyrus numlock lesioned oph
 LocalWords:  Exp VolumeProcessingLibrary DICOM ie jpeg alt Unselect OBJ obj