Installation

Software Dependencies

Ultraliser has the following optional dependencies:

1. OpenMP, a multi-threading library for parallel processing on multi-core CPUs.
2. libTIFF, which gives support for the Tag Image File Format (TIFF), a widely used format for storing image data.
3. libhdf5, or the Hierarchical Data Format 5 (HDF5) library for stroring data.
4. Eigen3, a template library for linear algebra: matrices, vectors, numerical solvers, and related algorithms.
5. BZip2, a high quality data compressor.
6. ZLIB, for data compression.
7. FMT, a formatting library providing a fast and safe alternative to C stdio and C++ iostreams.
8. GLM, a header only C++ mathematics library for graphics software based on the OpenGL Shading Language (GLSL) specifications.

Installation

1. Clone the repository into your file system.

$ git clone https://github.com/BlueBrain/Ultraliser  


Cloning into 'Ultraliser'...
remote: Enumerating objects: 15827, done.
remote: Counting objects: 100% (2788/2788), done.
remote: Compressing objects: 100% (858/858), done.
remote: Total 15827 (delta 2107), reused 2583 (delta 1923), pack-reused 13039
Receiving objects: 100% (15827/15827), 8.43 MiB | 6.18 MiB/s, done.
Resolving deltas: 100% (14815/14815), done.

2. Create a build directory.

$ cd Ultraliser && mkdir build && cd build 

3. Run CMake.

$ cmake .. 
-- The C compiler identification is GNU 9.4.0
-- The CXX compiler identification is GNU 9.4.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Found OpenMP_C: -fopenmp (found version "4.5") 
-- Found OpenMP_CXX: -fopenmp (found version "4.5") 
-- Found OpenMP: TRUE (found version "4.5")  
-- Found OpenMP -fopenmp, -fopenmp,, /usr/lib/gcc/x86_64-linux-gnu/9/libgomp.so/usr/lib/x86_64-linux-gnu/libpthread.so
-- Found TIFF: /usr/lib/x86_64-linux-gnu/libtiff.so (found version "4.1.0") 
-- Found TIFF: /usr/include/x86_64-linux-gnu, /usr/lib/x86_64-linux-gnu/libtiff.so
-- HDF5: Using hdf5 compiler wrapper to determine CXX configuration
-- Found HDF5: /usr/lib/x86_64-linux-gnu/hdf5/serial/libhdf5_cpp.so;/usr/lib/x86_64-linux-gnu/hdf5/serial/libhdf5.so;/usr/lib/x86_64-linux-gnu/libpthread.so;/usr/lib/x86_64-linux-gnu/libsz.so;/usr/lib/x86_64-linux-gnu/libz.so;/usr/lib/x86_64-linux-gnu/libdl.so;/usr/lib/x86_64-linux-gnu/libm.so (found version "1.10.4") found components: CXX HL 
-- Found HDF5: /usr/include/hdf5/serial, /usr/lib/x86_64-linux-gnu/hdf5/serial/libhdf5_cpp.so;/usr/lib/x86_64-linux-gnu/hdf5/serial/libhdf5.so;/usr/lib/x86_64-linux-gnu/libpthread.so;/usr/lib/x86_64-linux-gnu/libsz.so;/usr/lib/x86_64-linux-gnu/libz.so;/usr/lib/x86_64-linux-gnu/libdl.so;/usr/lib/x86_64-linux-gnu/libm.so
-- Found EIGEN3: /usr/include/eigen3
-- Found GLM: /usr/include  
-- GLM: /usr/include
-- Found fmt: /usr/include
-- Found ZLIB: /usr/lib/x86_64-linux-gnu/libz.so (found version "1.2.11") 
-- Found ZLIB: /usr/include, /usr/lib/x86_64-linux-gnu/libz.so
-- Found BZip2: /usr/lib/x86_64-linux-gnu/libbz2.so (found version "1.0.8") 
-- Looking for BZ2_bzCompressInit
-- Looking for BZ2_bzCompressInit - found
-- Found BZip2: /usr/include, /usr/lib/x86_64-linux-gnu/libbz2.so

*****************************************************************************************
* Dependencies Verification
   * OpenMP        OK
   * HDF5          OK
   * TIFF          OK
   * EIGEN3        OK
   * ZLIB          OK
   * BZIP2         OK
   * GLM           OK
   * FMT           OK
   * NRRD Deps.    OK
*****************************************************************************************

-- Configuring done
-- Generating done
-- Build files have been written to: /projects/Ultraliser/build

If all the dependencies are installed, it will be shown in the Dependencies Verification section that all the dependencies are installed. All the dependencies are optional and Ultraliser can compile without them, but indeed, some features will be missing.

To ensure that all the dependencies are installed, you would better use the following command on linux

$ sudo apt-get install libtiff-dev libeigen3-dev libhdf5-dev libbz2-dev libzip-dev libfmt-dev libglm-dev 

If you are using a macOSX system, you can use the MacPorts projects to install the dependencies using the following command

sudo port install tiff hdf5 eigen3 eigen3-devel libfmt glm

4. Compile the software using as many cores as you can.

$ make -j 6 

Missing Features & Dependencies

OpenMP

If OpenMP is missing, the embarrassingly parallel chunks of the code will be excuted in a single thread.

libTIFF

If libTIFF is missing, ultraMask2Mesh will NOT be able to load TIFF masks.

libTIFF can be installed on Ubuntu using the package manager with the following command

$ sudo apt-get install libtiff-dev 

libTIFF can be installed on macOSX using the MacPorts projects with the following command

$ sudo port install tiff 

libHDF5

If libHDF5 is missing, Ultraliser will NOT be able to load any .H5 files, such as .H5 morphologies and .H5 meshes. The following applications will be directly affected:

• ultraAstroMorpho2Mesh
• ultraNeuroMorpho2Mesh
• ultraVessMorpho2Mesh

Additionally, the ultraH5MeshConverter will NOT be compiled.

libHDF5 can be installed on Ubuntu using the package manager with the following command

$ sudo apt-get install libhdf5-dev 
 

libHDF5 can be installed on macOSX using the MacPorts projects with the following command

$ sudo port install hdf5 

Eigen3

If Eigen3 is missing, ultraNeuroMorpho2Mesh and ultraAstroMorpho2Mesh applications will NOT use the FEM method to reconstruct three-dimensional somatic profiles on a physically plausible basis. Rather, the soma will be merely represented by a symbolic sphere.

Eigen3 can be installed on Ubuntu using the package manager with the following command

$ sudo apt-get install libeigen3-dev 
 

Eigen3 can be installed on macOSX using the MacPorts projects with the following command

$ sudo port install eigen3 eigen3-devel

BZip2 and ZLIB

If BZip2 or ZLIB are missing, then ultraVolume2Mesh will NOT be able to load NRRD volumes.

BZip2 and ZLIB can be installed on Ubuntu using the package manager with the following command

$ sudo apt-get install libbz2-dev libzip-dev 
 

FMT

If fmt library is missing, then ultraVolume2Mesh will NOT be able to load NRRD volumes.

fmt can be installed on Ubuntu using the package manager with the following command

$ sudo apt-get install libfmt-dev 

GLM

If the GLM library is missing, then ultraVolume2Mesh will NOT be able to load NRRD volumes.

GLM can be installed on Ubuntu using the package manager with the following command

$ sudo apt-get install libglm-dev 

Tested Platforms

Ultraliser has been successfully tested on the following operating systems:

1. Ubuntu 18.04 and 20.04.
2. ReaHat
3. macOSX Montery and Big Sur.

NOTE: The current version has never been tested on Windows.