License and Disclaimer of Warranty:

The knowledge guided active mesh software (KAM) was developed for automatic segmentation of brain cortical structures from T1 weighted MR image. This software is provided as it is and no warranty for its correctness. The authors do not accept any liability for any defect or any data loss in this software.

This software is designed for research purposes only and has not been evaluated by the United States Food and Drag Administration (FDA) or other agencies, therefore clinical application are not recommended.

KAM has integrated part of brain extraction tool (BET) code for brain extraction as followings. A brain mask is generated by applying brain mesh model to individual head images. Then BET is applied to further remove non brain tissues. More BET information could be found on the webpage: http://www.fmrib.ox.ac.uk/fsl/. 
   
When publishing results using this tool, acknowledge the source by including the statement, {The knowledge guided active mesh software (KAM) was provided by Division of Translational Imaging Research at St. Jude Children's Research Hospital and is available at http://www.stjude.org/kam}.

This software is developed and tested on SGI (IRIX) system specified below. We encourage users to compile and test on similar systems. It may need some modifications on other systems. Your improvement and feedbacks will be appreciated.

The detailed methodology of this tool could be found in:
Shan ZY, Parra C, Ji Q, Jain J, Reddick WE. A Knowledge-Guided Active Model Method of Cortical Structure Segmentation on Pediatric MR images. J Magn Reson Imging, 24:779-789, 2006.

Shan ZY, Parra C, Ji Q, Ogg RJ, Zhang Y, Laningham FH, Reddick WE. A digital pediatric brain structure atlas from T1-weighted MR images. Lect Notes Comput Sc, 4191:332-339, 2006.

Installation:

SYSTEM ENVIRONMENT
---------------------
	KAM software is developed on Silicon Graphics Inc. (SGI) IRIX operating system. This version of software has been compiled and run successfully in SGI Origin 350-8p (800 MHz/8MB cache, 9GB memory) work station. The minimum processor speed is 500 MHZ and 1 GHz memory. The stack size limit should be set over 300 MBytes. The software needs two types of C++ compilers: CC (MIPSpro C++ compiler) and gcc (GNU C++ compilers). Besides system requirements, the Fluid Light Toolkit (FLTK) should be installed in the system. The FLTK version used for KAM software is 1.1.1.6. The FLTK could be downloaded and its detailed information on webpage: http://www.fltk.org

Set environment variables, you need specify FLTK directory installed:

setenv FLTKDIR {FLTKDIR}
setenv FLTKINCLUDE {FLTKDIR}

For an example, if you installed FLTK into /usr/freeware/, type:

setenv FLTKDIR "/usr/freeware/lib64/"
setenv FLTKINCLUDE "/usr/freeware/include" 



INTSTALL
----------

a) Extracting files:

       The software is distributed as compressed format kam.tar.gz. Using shell command gzip to decompress the file:

gzip -d kam.tar.gz
tar -xvf kam.tar 

After file extraction, there are 3 directories in kam directory: atlas src bin. 

b) Install, type:

cd src
make install

After installation, in bin directory, there should be 4 binary executables:

KAM
affinreg
distrans
abet

those are the programs needed to run KAM

Running the software: 

ENVIRONMENT VARIABLES
-------------------------

After installation, an environment variable, ATLASPATH, must be set to the full pathname of the atlas path (under the kam directory, {kam}/atlas/) in order to run the software.

Ideally this variable should be set in the user's init scripts: .profile or .bashrc or .cshrc or similar. For an example, if the software was installed into /usr/freeware/ then
 
setenv ATLASPATH "/usr/freeware/kam/atlas/"

Or you must set ATLASPATH each time.

Additionally, it is convenient to add {kam}/bin to the PATH variable in order to run the software from any directory. We highly recommend you running KAM form image directory! For an example, if the software was installed into /usr/freeware/ then

setenv KAMDIR /usr/freeware/kam;
setenv PATH ${PATH}:$KAMDIR/bin;
rehash;    

OR
set path=(/usr/freeware/kam/bin $path);
rehash;

RUNNING KAM
--------------
Type:

KAM 

 

INPUT/OUTPUT
--------------
KAM reads raw image with unsigned 16 bit integer format. You may choose open image if the specified image already resample into 1mm*1mm*1mm, 256*256*256 transverse slices. Otherwise the image should be opened by select Image -> Import Image from menu and specify image resolution, direction, and matrix size.
KAM outputs cortical structures in binary raw image with unsigned 8 bit integer format if Volume -> Save Current Volume or Volume -> Save All Volume commands from menu is selected. The cortical structures will be saved in current working directory end with file name of structure.vol, for an example r-l-frontal.vol for left frontal lobe. Therefore, we highly recommend running the KAM under individual subject MR image directory. Additionally, it is also highly recommend running KAM under different directories for different individual images because KAM generates some different temporary files with the same names despite the different individual images.

EXCUTION
----------
Select the desired structure name from the Triangle Mesh List.
Select Atlas. KAM has 3 atlases included in the package. We recommend using young atlas for image from subject with ages under 9.5 yrs old, middle atlas for those with ages from 9.6 to 12.9 yrs old, and old atlas from those with ages equal or above 13 yrs old.
Select Excute (lower buttons) will start automatic structure delineation process.
We have tested the KAM for its robustness by visual inspection of segmented structures from image with different pulse sequence, MR machine, and images from systems with different magnetic field strength, more than 95% delineated structures with acceptable accuracy by visual inspection. 
Manual editing; If higher accuracy is wanted or KAM failed in some subtle locations, the volume could be adjusted: select the structure name on the right above corner. Then using middle button of the mouse to outline the regions to be edited; Select command of Contour -> Filled Drawed Contour -> Fill and then click left mouse button to add the edited region to the structure selected or Contour -> Filled Drawed Contour -> UnFill and then click right mouse button to erase the edited region from the selected structures.
The active mesh has three parameters to control its slithering behavior. The parameters could be adjusted by select Options (lower buttons). External determines the extent by which the mesh toward image landmarks. Continuity controls the mesh triangle regularities. Curvature controls the curvature of the mesh. The last two parameters control smoothness of the structure model.

COMMON ERRORS
-----------------
If KAM runs correctly but renders totally wrong cortical structures, please double check the correctness of atlas path.
If KAM runs correctly but renders partly wrong cortical structures, please double check if KAM create specific transformation matrix and distance map for correspond individual images. To do that, you must clean previous transformation matrix and distance map images, therefore, we highly suggest you to run different subjects under different directories.  
  
           
  

     
     
