Skip to content

Build instructions

Jump to bottom
Ramón Casero edited this page Oct 27, 2017 · 18 revisions

Table of Contents

Created by gh-md-toc

Quickstart

If you just need pure Matlab functions, simply:

  1. Clone the repository, replacing GITHUB_USERNAME by your github username

     git clone https://GITHUB_USERNAME@github.com/vigente/gerardus

  2. run from Matlab the script gerardus/matlab/add_gerardus_paths.m to add the Gerardus toolboxes to your Matlab path.

If you want to use also the Matlab MEX functions and C++ programs, then you need to:

  1. Check that you have the necessary dependencies
  2. Use CMake + make (Linux) or CMake + VisualStudio (Windows) to build and install Gerardus

List of dependencies for building Gerardus

To save some time in Linux

One-liner for linux that installs everything except ITK and Matlab. ITK will be downloaded and built by the Gerardus CMakeLists.txt script, and Matlab has to be installed separately. Depending on your version of Matlab, you may have to change the version of g++, but the CMake script will let you know which.

  • From Matlab R2013b to R2016a (inclusive)

      sudo apt install git cmake g++ g++-4.7 m4 libgl1-mesa-dev

  • From Matlab R2016b to at least R2017b (inclusive)

      sudo apt install git cmake g++ g++-4.9 m4 libgl1-mesa-dev

Detailed for Linux, Windows and MacOS X

  • Git client

    • Linux users: git command line client.

      sudo apt install git

    • Windows users: Git for Windows (command line and GUI) or TortoiseGit (GUI)

    • Mac OSX users: git command line client.

  • C++ compiler

    • Linux users, when you run cmake, it will let you know which g++ version you need for your Matlab version, e.g. g++-4.4 or g++-4.7. If the Matlab version is too new, you'll get the error I do not know which version of gcc/g++ is needed for Matlab RXXXXX.. If so, check here which g++ version you need), and add a line to the gerardus root CMakeLists.txt in the block

         if("${MATLAB_VERSION}" MATCHES "R2012a")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.4")
   elseif("${MATLAB_VERSION}" MATCHES "R2012b")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.4")
   elseif("${MATLAB_VERSION}" MATCHES "R2013a")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.4")
   elseif("${MATLAB_VERSION}" MATCHES "R2013b")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.7")
   elseif("${MATLAB_VERSION}" MATCHES "R2014a")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.7")
   elseif("${MATLAB_VERSION}" MATCHES "R2014b")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.7")
   elseif("${MATLAB_VERSION}" MATCHES "R2015a")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.7")
   elseif("${MATLAB_VERSION}" MATCHES "R2015b")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.7")
   elseif("${MATLAB_VERSION}" MATCHES "R2016a")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.7")
   elseif("${MATLAB_VERSION}" MATCHES "R2016b")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.9")
   elseif("${MATLAB_VERSION}" MATCHES "R2017a")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.9")
   elseif("${MATLAB_VERSION}" MATCHES "R2017b")
     set(GCC_VERSION_REQUIRED_BY_MATLAB "4.9")
   else()
     message(FATAL_ERROR 
       "I do not know which version of gcc/g++ is needed for Matlab ${MATLAB_VERSION}.\nPlease update gerardus/CMakeLists.txt with this information.")
   endif()

    • you also need the binary called g++, even if it won't be used (this is a bug in our build system)

    • Mac users can install Xcode free from Apple's App Store, which includes gcc. After installing Xcode you need to install the command-line tools - to do this open the preferences window in Xcode (start Xcode, open the Xcode menu and choose Preferences). Then click the Downloads tab and click the install button next to the Command Line Tools in the Components list.

    • For windows users, Visual C++ Express is available free from Microsoft and includes C++ compilers. You also need to add your Matlab version to gerardus file FindMatlab.cmake, if it's not already there

  • CMake (version >= 2.8.8)

    • Linux users:

      sudo apt install cmake
  • m4 (GNU M4 is an implementation of the traditional Unix macro processor)

    • Linux users:

      sudo apt install m4
  • OpenGL library

    • Gerardus has this dependency because MatlabImportFilter uses the _image type from CGAL_ImageIO, which depends on OpenGL to build.

    • Linux users: You need the development package of the OpenGL library. E.g. in Ubuntu

         sudo apt install libgl1-mesa-dev
  • Insight Toolkit v4.3.1
    • In linux, ITK gets installed automatically by our build system
    • In MacOS X, it may get installed automatically, but I haven't tested it. If it doesn't, see "Notes for building ITK by hand" below
    • Windows users need to build the source code and install by hand (see the ITK Software Guide for details)
  • Matlab (currently tested with R2012a, R2012b, R2013b, R2014a, R2016b)

    • Matlab has its own installer for each operating system (Linux, Windows, MacOS X)

    • Note for Linux / MacOS X users: Add the matlab bin directory to the path. For example, add to your file ~/.bashrc (don't use symlinks or the build will fail because CMake won't find the correct Matlab root path)

         export PATH="/opt/MATLAB/R2016b/bin:$PATH"

    • Note for Windows users: Similarly to the previous step, add to the Path environment variable the path to your Matlab LIBMEX.DLL and LIBMX.DLL libraries, e.g. C:\Program Files\MATLAB\R2010b\bin\win32 (32 bit) or C:\Program Files\MATLAB\R2010b\bin\win64 (64 bit)Matlab

Notes for building ITK by hand (only needed by Windows users)

  • If you build ITK separately, you need to set the following variables in your CMake build of ITK

        CMAKE_BUILD_TYPE   Release (this one ignored by Windows)
    BUILD_SHARED_LIBS  ON
    ITK_USE_REVIEW     ON
    ITK_LEGACY_REMOVE  ON
    BUILD_DOCUMENTATION   OFF
    BUILD_EXAMPLES        OFF
    BUILD_TESTING         OFF
    • Windows users can do this checking the "Advanced" box in the CMake interface, and then checking the ITK_USE_REVIEW and ITK_LEGACY_REMOVE. If using Visual Studio, then the CMAKE_BUILD_TYPE entry will be ignored anyway, because Visual Studio is a multi-configuration sytem

  • Note for MacOS X: this site has instructions for building ITK separately (although they forget to mention that you click "Generate" on the CMake GUI at the end)

  • Note for Linux and MacOS X: ITK needs to be compiled with the same version of the compiler used for Matlab. This can be ensured setting the following CMake variables (e.g. Matlab2012a/Matlab2012b/Matlab2013a for Linux require gcc 4.4, and Matlab2013b/Matlab2014a require gcc 4.7)

          CMAKE_C_COMPILER gcc-4.4
      CMAKE_CXX_COMPILER g++-4.4

or

        CMAKE_C_COMPILER gcc-4.7
        CMAKE_CXX_COMPILER g++-4.7

  • Linux and MacOSX users can save time running cmake like this:

       $ cmake -DBUILD_SHARED_LIBS=ON -DITK_USE_REVIEW=ON \
   -DCMAKE_BUILD_TYPE=Release -DITK_LEGACY_REMOVE=ON \
   -DCMAKE_C_COMPILER=/usr/bin/gcc-4.4 \
   -DCMAKE_CXX_COMPILER=/usr/bin/g++-4.4  ..

or

        $ cmake -DBUILD_SHARED_LIBS=ON -DITK_USE_REVIEW=ON \
        -DCMAKE_BUILD_TYPE=Release -DITK_LEGACY_REMOVE=ON \
        -DCMAKE_C_COMPILER=/usr/bin/gcc-4.7 \
        -DCMAKE_CXX_COMPILER=/usr/bin/g++-4.7  ..
  • Notes for Windows users:
    • Start Visual Studio as Administrator. This is required to install ITK
    • The ITK folder must be close to the root directory C:/>, because sometimes ITK gives compilation problems in Windows if the paths to files are very long strings
    • It's important to select "Release" instead of "Debug" from the pull-down configuration menu above the Solution Explorer. This will enable to build and install the Release version of ITK, which will then be needed by the Release build of Gerardus
    • Click on "Start" -> "My computer" -> "View system information", and in the "Advanced" tab click on "Environment Variables". Select the System variable Path, and click "Edit". Add the path to the ITKCOMMON.DLL library, e.g. C:\Program Files\ITK\bin.

Build and install Gerardus

Instructions for Linux and Mac users

  1. Run from the command line

     # Create a build directory for Gerardus
 $ cd gerardus
 $ mkdir build
 $ cd build
 # First configuration run (this will download and build ITK)
 $ cmake ..

  2. If everything went well, you'll see a message like the one below. Do as the message says to install ITK

     -- ******************************************************************************
 -- ITK built successfully. Now you need to install it manually. For that, run
 --    pushd "/home/myname/Software/gerardus/cpp/src/third-party/InsightToolkit-4.3.1/bin"
 --    sudo make install; popd
 -- If ITK installed successfully, you can then run
 --    cmake ..
 -- again to finish configuring Gerardus.
 -- ******************************************************************************

  3. Continue building and installing Gerardus:

     # Second configuration run (this will configure all Gerardus)
 $ cmake ..
 # Build and install Gerardus code (add e.g. flag -j6 to use 6 processors)
 $ make install

  4. If the matlab command is not in the path, Gerardus will not know where to find Matlab. In that case, it's necessary to provide to the cmake lines above a flag with the path to the Matlab root directory, e.g. -DMATLAB_ROOT=/usr/local/MATLAB/R2012a/.

  5. Open Matlab from the matlab directory and run script add_gerardus_paths.m to add the Gerardus toolboxes to the Matlab path

     # from the linux command line
 $ cd ../matlab
 $ ./matlab &
 # from the Matlab command line
 >> add_gerardus_paths.m

  6. If you get an error message similar to this when running a MEX file

     Invalid MEX-file
 '/home/jdoe/workspace/gerardus/matlab/CgalToolbox/cgal_meshseg.mexa64':
 /usr/local/MATLAB/R2012b/bin/glnxa64/../../sys/os/glnxa64/libstdc++.so.6:
 version `GLIBCXX_3.4.15' not found (required by
 /home/jdoe/workspace/gerardus/matlab/CgalToolbox/cgal_meshseg.mexa64)

the problem is that your system libstdc++.so (linked to by the ITK libraries) is slightly different from Matlab libstdc++.so (linked to by the libmex.so library). Even if both libstdc++.so correspond to e.g. g++ v4.4, they have different minor versions, and that's were the error comes from. The solution is to delete the soft link in Matlab that points to Matlab's version of the library, and replace it by a soft link to the system's library. Library locations and names will vary between Linux distributions and Matlab versions, but for example, for Matlab R2012b with a default install:

    cd /usr/local/MATLAB/R2012b/sys/os/glnxa64/
    sudo rm libstdc++.so.6
    sudo ln -s /usr/lib/gcc/x86_64-linux-gnu/4.4/libstdc++.so

Instructions for Windows users

  1. Open file gerardus\CMakeLists.txt with your CMake program

  2. Click on the "Configure" button. Specify the generator for this project (the one we have tested is "Visual Studio 10" with "Use default native compilers").

  3. Click on the "Generate" button

  4. Open file gerardus\build\GERARDUS.sln with your development environment (e.g. Visual Studio 10)

  5. Select "Release" from the configuration pull-down menu above the Solution Explorer, instead of "Debug"

  6. Select "Build -> Build Solution" from the menu. This will build the libraries and MEX files

  7. In the "Solution Explorer", right click on "INSTALL" and select "Build". This will install the libraries and MEX files

  8. Click on "Start" -> "My computer" -> "View system information", and in the "Advanced" tab click on "Environment Variables". Select the System variable Path, and click "Edit". Add the path to the ITKCOMMON-*.DLL library, e.g. "C:\Program Files\ITK\bin". Make sure that this variable also contains the path to where the Matlab libmex.dll file is, e.g. "C:\Program Files\MATLAB\R2012\bin\win64", or add them if necessary. After editing the Path variable you'll need to reboot Matlab.

  9. Launch Matlab, change directory to gerardus\test, and run script add_gerardus_paths.m to add the Gerardus toolboxes to the Matlab path, and the directories with DLLs to the system path

     % from the Matlab command line
 >> add_gerardus_paths.m

Notes on MEX functions provided by Gerardus

Gerardus contains Matlab function that can be run directly without building any code. There are also C++ programs and C++ MEX files that need to be compiled and installed before they can be run. These instructions explain how to that.

After building and installing Gerardus, you should have the command line programs and Matlab MEX functions listed below.

Command line programs (file names given following the linux convention. In Windows, executables have the extension .exe):

  • gerardus/programs/
  • extractVoxelCoordinatesFromSegmentationMask
  • padSegmentationMaskWithVoxels
  • resize3DImage
  • rigidRegistration2D
  • rotate3DImage
  • skeletonize3DSegmentation
  • vesselness3DImage

Matlab MEX functions (file names given following the linux 64 bit convention. In linux 32 bit, Windows 32/64 bit and Mac 32/64 bit the extension is different):

  • gerardus/matlab/
  • PointsToolbox/sparse_breakdown.mexa64
  • PointsToolbox/mba_surface_interpolation.mexa64
  • ItkToolbox/itk_imfilter.mexa64
  • ItkToolbox/itk_registration.mexa64
  • ItkToolbox/itk_pstransform.mexa64
  • ThirdPartyToolbox/dijkstra.mexa64
  • FiltersToolbox/bwregiongrow.mexa64
  • FiltersToolbox/im2dmatrix.mexa64
  • CgalToolbox/cgal_insurftri.mexa64
  • CgalToolbox/cgal_closest_trifacet.mexa64

Elastix

Our Matlab function elastix.m makes use of the binary elastix developed by Stefan Klein and Marius Staring. This binary needs to have been installed in the system so that it's visible to Matlab.

Linux

For linux systems:

  1. Download the Linux 64 bit binaries, provided as a .tar.bz2 file.

  2. Uncompress and save all the content to a new directory /tmp/elastix.

  3. Move the directory to /opt

     sudo mv /tmp/elastix /opt

  4. Change owner to root

     sudo chown -R root:root /opt/elastix

  5. Link to the binaries from a system directory so that they are visible to the system, and by extension, to Matlab

     cd /usr/local/bin
 sudo ln -s /opt/elastix/bin/transformix
 sudo ln -s /opt/elastix/bin/elastix

  6. Add the directory with the library libANNlib.so to the library path so that the elastix binaries can find it. This will be done automatically when you open a terminal if you add to your .bashrc the line

     export LD_LIBRARY_PATH=/opt/elastix/lib:$LD_LIBRARY_PATH

    From now on, every time you launch Matlab from a new terminal, it will be able to find libANNlib.so. If you have just edited .bashrc without closing the terminal and opening a new one, to enable the new path you need to reload the file running

     source .bashrc
Clone this wiki locally