This is a collection of software designed to process 3D images of the cerebral cortex at a sub-millimetre scale, for example high-resolution MRI. In particular, it implements Bok’s equivolumetric model for extracting cortical layers while compensating for cortical curvature.

If you use this work in an academic publication, please cite the relevant references (see doc/references.bib).

This package can be used on the command line, the main interface is through shell scripts. Here is a short introduction. See below for installation instructions.

1. Set up the necessary environment using bv_env.sh:

   . </path/to/installation>/bin/bv_env.sh </path/to/installation>
   

2. Create a directory to process your data, and copy the contents of the scripts/ sub-directory thereunder:

   cp -R </path/to>/scripts/* .
   

3. Put your input data into place. The only input is classif.nii.gz, which should contain a voxel-wise tissue classification in signed 16-bit pixel type, with 0 for exterior voxels, 100 for cortical gray matter, and 200 for subcortical white matter.

4. Run the scripts that correspond to the output that you need. Each script should be run from within its own sub-directory (first cd to this directory, then run ./script.sh).

   • For the Laplace model, you need to run heat.sh. This should work out of the box, without the need for tuning any parameter. Outputs are the Laplace field under heat/heat.nii.gz, and the curvature field under heat_div_gradn.nii.gz.
   • For Bok’s equivolumetric depth, you need to run heat.sh, then isovolume.sh. The result is output in isovolume/pial-volume-fraction.nii.gz. You can tune parameters in isovolume.sh, most importantly the step size (--step) can be adapted to the spatial resolution and required accuracy.
   • For calculating the Euclidian depth along Laplace traverses, you first need to run heat.sh. Then, you have two choices:
     • Using the fast upwinding method in upwind-euclidean.sh.
     • Using the slower advection method in laplace-euclidean.sh.
   • For parcellating the cortex into volumetric traverses, you need to run distmaps.sh, then heat.sh, and finally column-regions.sh. The main parameter is --goal-diameter at the end of the script, it controls the target diameter of merged regions (in millimetres). The --step parameter is also relevant here.

We are planning on packaging highres-cortex, and making it available as part of the graphical installer of BrainVISA. For now you have to compile it as described below.

The script bootstrap_compile.sh can be used to download, configure, and build highres-cortex:

wget https://github.com/ylep/highres-cortex/raw/master/bootstrap_compile.sh
chmod +x bootstrap_compile.sh
./bootstrap_compile.sh

The script is interactive, and will require some input from you.

• If you are on Ubuntu 14.04 or 16.04 LTS, this script will ensure that all the required dependencies are present on your machine, and propose their installation otherwise. For any other distribution, or any other version of Ubuntu, you have to install the dependencies manually.
• You will also be asked for a base directory to contain the downloaded sources, and the build process. You will need about 1.5 GB of free space in this directory.

The step-by-step approach in the next section performs essentially the same steps as the bootstrapping script, use that if you want to customize the build process.

You can compile this package as part of the BrainVISA source tree, which is based on CMake and uses a custom-made driver called bv_maker.

1. Install the dependencies. Under Ubuntu, the required packages are: subversion git cmake make gcc g++ gfortran pkg-config libblitz0-dev libsigc++-2.0-dev libxml2-dev libqt4-dev libboost-dev zlib1g-dev libtiff-dev libgsl0-dev python2.7-dev python-sip-dev python-numpy python-six libqt4-sql-sqlite.

2. Bootstrap the bv_maker tool:

   svn export --username brainvisa --password Soma2009 https://bioproj.extra.cea.fr/neurosvn/brainvisa/development/brainvisa-cmake/branches/bug_fix /tmp/brainvisa-cmake
   cd /tmp/brainvisa-cmake
   cmake -DCMAKE_INSTALL_PREFIX=. .
   make install
   

   Detailed instructions can be found in this Introduction to bv_maker (login brainvisa, password Soma2009).

3. Create the configuration file for bv_maker at $HOME/.brainvisa/bv_maker.cfg. Here is a minimal version of this file:

   [ source $HOME/brainvisa/source ]
     + brainvisa-cmake bug_fix
     + brainvisa-share bug_fix
     + soma-base bug_fix
     + soma-io bug_fix
     + aims-free bug_fix
     git https://github.com/neurospin/highres-cortex.git master highres-cortex
   
   [ build $HOME/brainvisa/build ]
     build_type = Release
     brainvisa-cmake bug_fix $HOME/brainvisa/source
     brainvisa-share bug_fix $HOME/brainvisa/source
     soma-base bug_fix $HOME/brainvisa/source
     soma-io bug_fix $HOME/brainvisa/source
     aims-free bug_fix $HOME/brainvisa/source
     + $HOME/brainvisa/source/highres-cortex
   

   Keep the following in mind if you want to customize this configuration file:

   • you need this line in the source section:

     git https://github.com/neurospin/highres-cortex.git master highres-cortex
     

   • you need this line in the build section:

     + </path/to/brainvisa/source>/highres-cortex
     

   • you need to enable the aims-free component and its dependencies brainvisa-cmake, soma-base, and soma-io; alternatively, just enable the anatomist group, which is a superset of these.

4. Run /tmp/brainvisa-cmake/bin/bv_maker, which will check out a local copy of the sources, configure them with cmake, and build thim with make.

5. You can then run the software directly from $HOME/brainvisa/build, as indicated in the Basic usage section.

• AIMS version 4.5 or later, an image processing library distributed as part of BrainVISA.
• GSL (GNU Scientific Library).
• Boost version 1.49 or later.
• Python version 2.6 or later.
• CMake version 2.6 or later, with its extension brainvisa-cmake (distributed with BrainVISA).
• Optional: the VipHomotopic command-line tool from the Morphologist image segmentation pipeline, distributed as a binary only tool with the BrainVISA installer.

The source code of this work is placed under the CeCILL licence (see LICENCE.CeCILL.txt). Compiled code that links to the GPL-licensed GSL forms a derivative work thereof, and thus must be redistributed under the GNU General Public Licence (see LICENCE.GPLv3.txt).