Skip to content

Installation instructions

Jump to bottom
evgueni-ovtchinnikov edited this page May 19, 2017 · 41 revisions

These instructions are for building SIRF under various scenarios. Please add or amend.

A strength of SIRF is that it uses the expertise of other well-developed Open Source packages for medical image reconstruction. A downside is that these external packages and their dependencies need to be installed. Within SIRF, there are various components that need to be built.

Currently we have 2 ways of installing SIRF: manually and using the so called SuperBuild.

The SuperBuild handles the compilation of most of the required software automagically.

SuperBuild Installation

To proceed with the SuperBuild one should clone the project SuperBuild and follow the instructions at the website. The SuperBuild has been tested on Linux and could/should work out of the box with MacOSX. Work is in progress for the Windows platform.

Although the SuperBuild is intended to save the user the pain of installing all the dependencies, we pragmatically still require the user to install a few packages: a C/C++ compiler, make and Cmake. Refer to the SuperBuild website for more specific instructions.

Please check also our pages with specific instructions for SIRF and MATLAB, and SIRF and Python.

Manual Installation

General Notes

Currently installation requires two steps - first the external packages and second the components of SIRF.

First steps: SIRF relies on external projects which we have forked so that you can build against versions we have tested. The forks are located here: https://github.com/CCPPETMR

  • STIR required for PET reconstruction,
  • ISMRMRD required for handling of MRI data in ISMRMRD format,
  • Gadgetron required for the reconstruction of MR data.

Installation instructions for ISMRMRD and Gadgetron can be found on the Gadgetron Wiki (expand menu on right hand side), but steps for Linux are given below.

If you have manufacturer's MR raw data, it will need to be converted to ISMRMRD format using tools such as siemens_to_ismrmrd available from the ISMRMRD Git site, or the SIRF siemens_to_ismrmrd clone .

Second Steps: SIRF needs to be built using CMake.

For most people it's probably easiest to use cmake-gui to get a GUI. You can also use cmake from the command line but this doesn't allow you to adjust variables so easily.

We recommend building all projects in a folder called build, and installing these all in a folder called install (set CMAKE_INSTALL_PREFIX). You also need SWIG and of course either Python or MATLAB (or both).

See below for specific caveats when you want to use MATLAB.

Steps on Linux

Please note that we recommend to use the SuperBuild on Linux. Steps below are for more adventurous people!

First install required dependencies, see https://github.com/CCPPETMR/CCPPETMR_VM/blob/master/scripts/INSTALL_prerequisites_with_apt-get.sh

The following lines are an example how you could build.

First create environment variables. This wiki currently uses csh syntax, but bash will look similar (remove set, and replace setenv A B with export A=B). You would want to add them to your .cshrc (or .bashrc)

# set locations according to your preference
set BUILD_PATH=~/devel/build/
set INSTALL_PATH=$BUILD_PATH/install
set SRC_PATH=~/devel
# set run-time paths for later
setenv PYTHONPATH $INSTALL_PATH/python:$SRC_PATH/ismrmrd-python-tools
setenv LD_LIBRARY_PATH $INSTALL_PATH/lib:$LD_LIBRARY_PATH
setenv SIRF_PATH $SRC_PATH/SIRF
set path=( $INSTALL_PATH/bin $path )

Please check also our pages with specific instructions for SIRF and MATLAB, and SIRF and Python.

Now download and install

# create variable that uses ccmake and above variables
# you could use cmake or cmake-gui
set CCMAKE="ccmake -DCMAKE_PREFIX_PATH:PATH=$INSTALL_PATH/lib/cmake -DCMAKE_INSTALL_PREFIX=$INSTALL_PATH"

mkdir -p $SRC_PATH
mkdir -p $BUILD_PATH
cd $SRC_PATH
git clone --recursive https://github.com/CCPPETMR/STIR
git clone --recursive https://github.com/CCPPETMR/ismrmrd
git clone --recursive https://github.com/CCPPETMR/gadgetron
git clone --recursive https://github.com/CCPPETMR/SIRF

cd $BUILD_PATH

mkdir STIR
cd STIR
$CCMAKE -DGRAPHICS=None -DBUILD_EXECUTABLES=OFF -DCMAKE_POSITION_INDEPENDENT_CODE=ON $SRC_PATH/STIR
make install
cd ..

mkdir ismrmrd
cd ismrmrd
$CCMAKE $SRC_PATH/ismrmrd
make install
cd ..

mkdir gadgetron
cd gadgetron
$CCMAKE $SRC_PATH/gadgetron
make install
cd ..    

mkdir SIRF
cd SIRF
$CCMAKE $SRC_PATH/SIRF
make install
cd ..

Updating

If you want to try the latest version of SIRF, do update as follows:

cd $SRC_PATH/SIRF
git pull
cd $BUILD_PATH/SIRF
$CCMAKE $SRC_PATH/SIRF
make install

Steps on MacOS

The above instructions using CMake are likely to work on MacOS. Alternatively, the script build-mac can be used for the MR components of this software. Instructions are in a comment at the top of the script. Essentially it sets environment variables and calls make for the various SIRF sub-folders.

Steps on Windows

Building SIRF on Windows Work in Progress and painful. Note that these instructions are for using Win64. You could try to use the 32-bit tools but it's probably not worth it.

When running CMake, it is important to select the correct 'generator'. This page is written for Visual Studio 2015 with 64bit development, so be careful to use the "Visual Studio 14 2015 Win64" generator.

Please use a very recent CMake (at least 3.7.2) on Windows.

These are steps that KT followed:

  1. Get Visual Studio Community Edition 2015 (free). Install with custom options and select C++ and "Python Tools for Visual Studio". You probably also want to select the git and github add-ons such that you don't need to install these separately.

  2. Get HDF5 libraries from https://support.hdfgroup.org/HDF5/release/obtain518.html (use the 64-bit, VS2015 version) and install (please use version 1.8.18). You could create an environment variable HDF5_ROOT to point to the folder where you extracted it, e.g. C:/Program Files/HDF_Group/HDF5/1.8.18/.

  3. Install Anaconda, use the 64-bit version. After this, you probably want to open a command prompt and type

    conda update conda
conda update --all
conda install docopt
pip install sphinx_bootstrap_theme

  4. Install Boost. KT got it from https://sourceforge.net/projects/boost/files/boost-binaries/1.63.0/boost_1_63_0-msvc-14.0-64.exe/download. It might be easiest to install in c:\boost for CMake to find it. Otherwise you could create an environment variable BOOST_ROOT that points to the folder where you installed it, e.g. C:/Users/krisf/Documents/devel/boost_1_63_0. Of course, you can set BOOST_ROOT also from in CMake.

  5. Install FFTW. KT got it from ftp://ftp.fftw.org/pub/fftw/fftw-3.3.5-dll64.zip. Unzip this file in a separate folder. Open your "Developer Command Prompt for VS2015". cd to the folder and execute

    lib /machine:x64 /def:libfftw3f-3.def
lib /machine:x64 /def:libfftw3-3.def
lib /machine:x64 /def:libfftw3l-3.def

You could create an environment variable FFTW3_ROOT_DIR to point to the folder where you extracted it.

  1. Compile ismrmrd and optionally Gadgetron. Instructions are here but we recommend the following

    • ismrmrd can be built using normal CMake (see also below for some info on setting relevant variables). If it doesn't find your HDF5 libraries, either set an environment variable HDF5_ROOT as above, or add a CMake variable in the GUI called HDF5_ROOT of type Path and set it.

      Sadly there seems to be a bug in the CMake files for HDF5 which causes linking errors. Here are some alternative solutions how to fix this in CMake after configuring:

      • set HDF5_hdf5_LIBRARY_RELEASE to C:/Program Files/HDF_Group/HDF5/1.8.18/lib/libhdf5.lib;C:/Program Files/HDF_Group/HDF5/1.8.18/lib/zlib.lib;C:/Program Files/HDF_Group/HDF5/1.8.18/lib/szip.lib
      • Or you can use C:/Program Files/HDF_Group/HDF5/1.8.18/lib/hdf5.lib but then add -DH5_BUILT_AS_DYNAMIC_LIB=1 to your CMAKE_C_FLAGS and CMAKE_CXX_FLAGS.

      You can probably use the files from Anaconda2 as well, but have to use the same fixes.

    • Compiling Gadgetron on Windows is currently quite hard. As an alternative, we normally run Gadgetron on our VM, and let SIRF communicate to that by forwarding port 9002 to the VM. Instructions are in xGadgetron\INSTALL.txt.

  2. Get SWIG. KT used http://prdownloads.sourceforge.net/swig/swigwin-3.0.11.zip and extracted it. You could add this folder to your PATH, or set SWIG_EXECUTABLE when running CMake.

  3. git clone SIRF

  4. Run CMake with SIRF as source, and build/SIRF as destination. Make sure CMake finds everything by setting STIR_DIR, BOOST_ROOT, HDF5_DIR etc etc. First run Configure and hope for the best. If bits are missing, set the variables appropriately. Some examples for the local settings used by KT that might help you:

  • Best to set CMAKE_INSTALL_PREFIX first and then Configure again. This configure might find more stuff. KT used C:/Users/krisf/Documents/devel/install-VC.
  • set BOOST_ROOT to something like C:/Users/krisf/Documents/devel/boost_1_63_0 if that is where you installed it. Note that if you don't see the BOOST_ROOT variable, you have to tick the "Advanced" box.
  • set FFTW3F_LIBRARY to C:/Users/krisf/Documents/devel/fftw-3.3.5-dll64/libfftw3f-3.lib and FFTW3_INCLUDE_DIR to C:/Users/krisf/Documents/devel/fftw-3.3.5-dll64/ (you will have to tick the "Advanced" box).
  • set ISMRMRD_DIR to C:/Users/krisf/Documents/devel/install-VC/lib/cmake/ISMRMRD
  • set STIR_DIR to C:/Users/krisf/Documents/devel/install-VC/lib/cmake
  1. Run Visual Studio, open the SIRF solution. Build the default target (probably in Release mode), and then the INSTALL target.
  2. Before you can run anything, you need to tell Windows where the DLLs are, which means adjusting your PATH. KT had to do
PATH=C:\Users\krisf\Documents\devel\fftw-3.3.5-dll64;C:\Users\krisf\Documents\devel\install-VC\bin;C:\Users\krisf\Documents\devel\boost_1_63_0\lib64-msvc-14.0;%PATH%
  1. Somehow tell Python where everything is (sorry, no pip install yet). For instance in your command prompt, before running Python, first do
Set PYTHONPATH=C:\Users\krisf\Documents\devel\install-VC\python;%PYTHONPATH%

  1. Obviously you will have to set your MATLAB path as well.

  2. To try the latest version of SIRF, pull from GitHub, run CMake, press Configure, then Generate, then Open Project, build and build project INSTALL (right-click on it and select Build).

See also our SIRF and MATLAB page.

Clone this wiki locally