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.
Set up the necessary environment using
bv_env.sh
:. </path/to/installation>/bin/bv_env.sh </path/to/installation>
Create a directory to process your data, and copy the contents of the scripts/ sub-directory thereunder:
cp -R </path/to>/scripts/* .
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.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 underheat_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 inisovolume.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.
- 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
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
.
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
.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).
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 dependenciesbrainvisa-cmake
,soma-base
, andsoma-io
; alternatively, just enable theanatomist
group, which is a superset of these.
Run
/tmp/brainvisa-cmake/bin/bv_maker
, which will check out a local copy of the sources, configure them with cmake, and build thim withmake
.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).