README
2005/5/26

BrainSplitter v1.0
-------------------

1. What is BrainSplitter?
2. How does BrainSplitter work?
3. About input files
4. Usage
5. Authors
 

1. What is BrainSplitter?

BrainSplitter is an object-oriented software for automatic extraction
of the midsagittal plane from brain surface images. BrainSplitter
divides the input brain mesh given in VMRL-format into two hemisphere
meshes and hence it is a potential tool for studying differences in
brain functions. The resulting meshes can be used for visualisation
and further analysis of the brain hemispheres.
BrainSplitter is a C++ -implementation, which applies a symmety-based
method presented by Y. Liu, R.T. Collins, W.E. Rothfus [1].


2. How does BrainSplitter work?

Input:
-Brain surface mesh in VRML-format
Output:
-The mathematical equation of midsagittal plane (a,b,c,d)
-Two VRML-files, containing right and left side of the given surface
 mesh  

BrainSplitter can be used in two modes:
a) To only search the midsagittal plane equation
b) To search the midsagittal plane equation and split the input mesh
   in two output mesh files

In first case (a) BrainSplitter searches the midsagittal plane of the
given input mesh and prints the coefficients of the equation for the
user. In this case only the input mesh filename must be given as a
parameter.

In the second case (b) BrainSplitter searches the midsagittal plane
of the given input mesh, prints the coefficients of the equation for
the user, generates two output mesh files containing the right and
left sides of the input mesh and fills the "empty" shear planes of
the output meshes with triangles. In this mode the input mesh
filename and two output mesh filenames must be given as parameters.  

See further details in "Usage".

The only mandatory parameter is the input mesh, and it must be given
always in order to run BrainSplitter. In addition there are some
parameters which affect the accuracy of the result and and can be
given by user. These parameters have tested ideal default values so
that they don't have to be given necessarily.

Such parameters are:
-number of slices
-slice dimensions
-the weight of each slice (self-generated weight matrix by the user)

See further details in "Usage".


3.About file formats

Input file format is compatible with VRML 1.0 -format. However, there
isn't any standadized way to present a surface mesh by using VRML 1.0  
and for that reason all the meshes of VRML 1.0 -format may not be
suitables for BrainSplitter.  For further details about suitable input
files, look the example meshes that are included in the BrainSplitter
package.

The output files generated by BrainSplitter follow the same definition
except that a commentfield containing information about the generation
of the mesh in question will be added. There will be also added
ShapeHints- and Material-nodes, that enable the visulization of the mesh
using external tools, for example JavaView.

4.Usage
  
The usage of BrainSplitter is based on commandline user interface.
The possible parameters of BrainSplitter:

-Input VRML-file
-Output file names (2 needed if given)
-Number of slices (default value: 32)
-Slice dimensions (default value: 64)
-Amount of run time log information (quiet / normal / verbose)
-Weight matrix generated by the user (the name of the text file containg
 the matrix)

The parameters must be given in the following order:
1. Input file
2. Output filenames if the mesh is wanted to be splitted
3. Other parameters, the order does not make a difference

The input file containing the VRML-mesh must be given every time the
application is launched. The input file is given the following way:

brainsplitter  <input mesh filename>
For example: >brainsplitter  input_mesh.wrl

If the output meshes are wanted to be generated, two desired output
mesh filenames must be given. Output mesh filenames are given the
following way:

brainsplitter <input mesh filename> <output mesh filename 1> <output mesh filename 2>
For example: >brainsplitter inputmesh.wrl result_right.wrl result_left.wrl    

Other parameters are: number of slices, size of the slice (slice dimensions),
the amount of run time log information (printed to the user) and the name of a
weight matrix file (in case that the user wants to use a self-generated
weight matrix). These parameters have their ideal default values so
that they do not have to be given if not wanted.

The number of slices is given the following way: --slices <desired number of slices>
For example: >brainsplitter input_mesh.wrl  --slices 48

The size of a slice is given the following way: --slice_dimensions <desired slice dimension>
For example: >brainsplitter input_mesh.wrl --slice_dimensions 32

The amount of run time log information (quiet / normal(default) / verbose)
is given the following way: --quiet or --verbose)
For example: >brainsplitter input_mesh.wrl --quiet

The quiet-mode only prints the coefficients of the equation of the misagittal
plane found. The verbose-mode print all the possible run time log information.

The self generated matrix file is given in a following way: --weights <filename.txt>
For example: >brainsplitter input_mesh.wrl --weights matrix_file.txt

The matrix file must contain every weight in an own line starting from
the first line of  the text file. Any empty lines between the weights or new lines
at the end of the file must not be left. Note that if the self generated weight
matrix is given as a parameter, the number of given weights must equal the number
of slices!      

The parameter identifiers have shorter aliases that can be used:
--slices = -s
--slice_dimensions = -d
--weights = -w
--verbose = -v
--quiet = -q

A simple help screen is printed to the user using the following command:
--help (or -?)
The default values are printed to the user using the following command:
--defaults
 
A simple example of the usage of BrainSplitter:

The user needs to find the equation of the midsagittal plane of the input
mesh "myBrains.wrl". She wants to use a self generated weight matrix
("myMatrix.txt"), which contains 20 weights (so that the default value (32)
of number of slices is not suitable). She doesn't want any run time log-
information to be printed. Now she would launch:

>brainsplitter myBrains.wrl --slices 20 --weights myMatrix.txt -quiet
or
>brainsplitter myBrains.wrl -s 20 -w myMatrix.txt -q

Now the program would answer:

Midsagittal plane equation coefficients are:
(a, b, c, d)

If she would want the input mesh to be split in two differend output
VRML-files, she should add the desired result file names:

>brainsplitter myBrains.wrl result_right result_left -s 20 -w myMatrix.txt  -q


5. Authors

BrainSplitter was implemented at the Department of Computer Sciences at the
University of Tampere on the Programming Project Work course during the term of 2004-2005.
Project team members were:

 Mikko Itaranta (project manager)
 Jouni Mutanen
 Ilkka Virtanen
 Esa Ylimaki


References

[1] Y. Liu, R.T. Collins, W.E. Rothfus.
Robust midsagittal plane extraction from normal and pathological
3-D neuroradiology images. IEEE Transactions on Medical Imaging,
20(3):175-192, 2001.

