This is a tutorial on how to build a MINC2-based registration platform on a linux based platform.
The most easy way (as of December 2011)
The compilation of some of the code fails when using a version of g++ higherthan 4.4, so it is important to use g++-4.4 for the entire build procedure. To get the compiler:
On Ubuntu Lucid 10.04 LTS:
> sudo apt-get install g++-4.4
And to make sure that the correct version of g++ is used:
> export CXX=g++-4.4
On Ubuntu Natty 11.04:
> sudo apt-get install gfortran gcc-4.4 g++-4.4 build-essential
> sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.5 40 --slave /usr/bin/g++ g++ /usr/bin/g++-4.5
> sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.4 60 --slave /usr/bin/g++ g++ /usr/bin/g++-4.4
> export CXX=g++-4.4
Please verify that the following
> g++ --version
> gcc --version
> gfortran --version
results in g++ and gcc reporting version 4.4.5, gfortran reporting 4.5.2
apt-get the following before you start on Ubuntu Lucid 10.04 LTS:
apt-get the following before you start on Ubuntu Lucid 11.04 LTS:
Get the modified Makefile (The basis for the quarantine comes from the Makefile that Vladimir Fonov created: original_Makefile_created_by_Vladimir).
To install all software:
or example with options:
Some libraries that are used by the registration software have unclear copyright issues, so we can not have these packages happily sit somewhere on the internet. You can request them from us, and after you have copied the tarballs over to the source (/realpath/build/dir/src) directory, you can complete the installation:
Create an environment script:
In a bash shell, you can now set the environment for the quarantine as follows:
Package and version information from August 24, 2011:
in Vladimir's Makefile
0.2 01 sept 2011
latest from Launchpad
(* fuzzy: these packages have ambiguous copyright issues, so should be requested for)
Testing your quarantine
You can test your quarantine using the with the following files: test_files_28september2012.tar.gz
Step 1, unpack the tarball:
There are two directories, the test_files_striatum_mutants directory contains sample input images and the initial-model directory contains files that determine the size and orientation of the output files of the registration pipeline. The test files were created such that there is (approximately) a 25% difference in the size of the striatum in the mutant files compared to the originals. To test all the software, you'll run a registration and recover these changes.
Step 2, set your environment:
Step 3, run the registration (on a single machine should take about 3-5 hours):
Step 4, recover the change in the striatum using R:
The easy way (before December 2011)
Get a single tarball here:
Untar that tarball, then compile all the necessary bits as follows, first checking for all dependencies:
Address any errors pointed out herein. If you get the following ppm related error output:
the missing ppm library can be installed using:
If you get the following GL/glut.h related error output:
the missing files can be installed using:
A fortran related error:
can be remedied by:
Once it finishes successfully, compile the code:
Note that you'll need to have python installed for this to work. It's also not been extensively tested yet, so please report any errors in the build process.
Some requirements: you need to have the build tools (C and C++ compiler, etc.) installed, as well as octave, the DBI perl module, and netpbm is highly recommended (the libnetpbm9-dev package on debian/ubuntu). For building python and its numeric libraries you'll also need a fortran compiler.
Once the software is compiled, source the installed environment file to use it:
You might need to edit that environment file to fit your local needs; in particular, if you have the Sun Grid Engine installed (which is highly recommended) in a non-default location, you'll need to add it onto the PATH.
The hard way: source code available from the Brain Imaging Centre at McGill
Many of the source files needed to install the registration platform can be found on the software page of McGill university. There you can find source code for different types of operating systems. The following tutorial was created by installing the software on Ubuntu Hardy.
Main software page:
Source code for linux systems:
The list (and order) of packages that are required from that website:
- xfmavg (comes from http://packages.bic.mni.mcgill.ca/scripts/)
That website will list multiple versions for each package - grab the highest version number unless indicated otherwise.
There are a number of libraries that the packages above depend on. This list is different for different platforms, and keeps changing, but here is a list that was used for Ubuntu Karmic:
General way of installing a package
Given a compressed package: package.tar.gz, located in /usr/local/minc2/src
Open a terminal and cd (change directory) to the parent directory where the files are:
Decompress the files:
cd to the directory containing the decompressed files:
Configure the installation procedure. The --prefix= flag will indicate where the package will be installed.
Compile the package:
Type `make install' to install the programs and any data files and documentation.
These commands may need to be preceded by sudo to give you the needed permissions to install the packages. For example:
You can remove the program binaries and object files from the source code directory by typing `make clean'. To also remove the files that `configure' created (so you can compile the package for a different kind of computer), type `make distclean'.
MINC2 specific installation procedures
The examples below will assume that MINC2 will be installed under /usr/local/minc2 and that the packages reside under /usr/local/minc2/src
MINC2 relies on the netcdf and hdf5 libraries for its data storage. These two libraries should be present on the system before MINC2 is installed, or the process will fail.
MINC2 is based on C-code, and thus a C compiler (e.g., gcc) is needed in order to compile the code. Typically gcc is available from your OS vendor (using apt-get or aptitude/synaptic). Make sure you choose the "-dev" or "-devel" binary package to ensure you have the developer files associated with the library. Since MINC2 is based on C-code, no interface for C++ or FORTRAN is needed. This can be made explict during the installation process by setting the environment variable for those compilers to "":
The commands that start with export work for a bash shell. If this command does not work, and you are running a csh/tcsh shell, the environment variables can be set using the command setenv:
The general installation procedure can be followed for hdf5, specifying only the --prefix flag for configure
On to the MINC2 libraries and software
The MINC2 library
For all versions of MINC2 upto 0.14, the configure option --enable-minc2 is needed. Any version 0.15 or later does not need this option anymore. The example below shows the commands for MINC2 version 0.15.
The --with-build-path flag for configure indicates where to look for libraries and include files which are needed for the installation of MINC2 (netcdf and hdf5).
General way of installing a MINC2 package
As usual, there are some exceptions to the rule. The packages bicpl and ebtks have slightly different configure options and the package mni_perllib has a different installation procedure all together.
This is a script that is not contained in any of the packages, but can be found here: http://packages.bic.mni.mcgill.ca/scripts/. Right click on xfmavg, and save the link as /usr/local/minc2/bin/xfmavg, in order for the program to reside in the bin directory where all the other executable will be. Then changes the mode of the file to make it executable.
Furthermore, the xfmavg script uses the GNU Octave library. This can be downloaded from their website http://www.gnu.org/software/octave/.
Register and/or Display
The following libraries must be installed before building Register and/or Display. Typically opengl (libGL), and glut (libglut) are available from your OS vendor (using apt-get or aptitude/synaptic). If possible, install the vendor version; otherwise see the websites listed below. Make sure you choose the "-dev" or "-devel" binary package to ensure you have the developer files associated with the library.
- OpenGL or Mesa
- OpenGL may be included with your OS, or see http://www.opengl.org/
- Mesa is a replacement for OpenGL, often included in linux distributions if not, see http://www.mesa3d.org/ (there is also a copy of Mesa on our ftp site ftp://ftp.bic.mni.mcgill.ca/pub/register+Display/MesaLib-3.4.tar.gz)
- a layer on top of OpenGL, may be included in your OS distribution
- if not, see http://reality.sgi.com/mjk/glut3/glut3.html
In addition make sure you have the header files for the X server (library libX11). This library is also typically available from your OS vendor (using apt-get or aptitude/synaptic). Make sure you choose the "-dev" or "-devel" binary package to ensure you have the developer files associated with the library.
It might be that compiling these tools using the `make' command fails. If that happens follow the ./configure part by:
In addition to the general configure flags, --with-image-ppm needs to be specified, i.e.,
The --with-minc2 configure flag does not need to be specified, i.e.,
For a more specific install (example):
This example tutorial assumes that MINC2 will be installed under /usr/local/minc2. During installation the folder /usr/local/minc2/bin is created and that folder will contain all the executables. The executables that are "known" (the programs you can run) by a shell are the ones it can find in the directories listed in the environment variable PATH. So what is left to do after installing the tools, is update that environment variable in order to find them.
To do this for all users in Ubuntu, update the PATH in the file /etc/environment:
For all users in Debian Sarge, update the PATH environment variable in /etc/profile and in /etc/bash.bashrc