TTK - the Topology ToolKit - Topological Data Analysis and Visualization

Please find below detailed instructions for the installation of TTK under MacOS.

TTK is also supported on other operating systems:
· Linux installation instructions (default target platform);
· Windows installation instructions.

This page describes installing TTK 0.9.6 on OSX, using High Sierra 10.13.6 and ParaView 5.5.2. The key differences from the linux installation involve how ParaView is compiled, installing certain dependencies, and setting up some of the paths for OSX. The following assumes that the target is to compile with OSX clang and uses homebrew for dependencies.

Other versions of earlier software packages may require slight variations in the installation procedure. For earlier versions of both software packages, you may want to check out previous versions of our installation notes for OSX:
· TTK 0.9.5 with ParaView 5.5.0.
· TTK 0.9.3 (and 0.9.4) with ParaView 5.4.1.
· TTK 0.9.2 with ParaView 5.4.0.

1. Downloads

Note: The instructions for this step are identical to those on linux:

TTK builds on top of ParaView for its main user interface. Thus, you will first need to download ParaView 5.5.2's source code. Note that TTK plugins for ParaView will only work with a version of ParaView compiled from source. Thus, if you already installed ParaView with a binary copy, you may need to un-install it before proceeding. Next, download TTK from our download page.

2. Installing the dependencies

Using homebrew, install:

cmake (tested with 3.12.1)
qt5 (tested with 5.11.1)
python2 (tested with 2.7.15_1)
vtk (tested with 8.1.1)

Using the command:

$ brew install cmake qt5 python2 vtk

a) Optional Dependencies

Using homebrew, one can install:

ffmpeg (tested with 4.0.2)
hdf5 (tested with 1.10.2_1)
tbb (tested with 2018_U5) -- needed for OSPRay
mpich (tested with 3.2.1_2) -- needed for OSPRay's execution
libomp (tested with 6.0.1) -- needed for OpenMP support

Using the command (or only parts of it):

$ brew install ffmpeg hdf5 tbb 
mpich

In order to enjoy the complete set of TTK features, we also recommend to install the following, optional dependencies:
· ZFP

And, in addition, one can install OSPRay and it's dependencies using:

Download and unpack ospray-1.6.1.x86_64.dmg from http://www.ospray.org/ getting_ospray.html (this installs in /opt/local/lib).
Download and unpack embree-3.2.0.x86_64.dmg from https://embree.github.io/ downloads.html (this installs in /opt/local/lib).
Download and unpack tbb2018_20180618oss_mac.tgz from https://github.com/01org/tbb/ releases. After expanding the .tar, I created a directory /opt/local/include/tbb and copied the headers there, while I also copied the library files to /opt/local/lib/. Why? The homebrew install for tbb doesn't created the *_debug.dylib's. One could also just install TBB entirely from the website and skip the homebrew install, but in theory these versions match

After doing so, you'll likely want to make sure that your commandline knows about ospray/embree/tbb, the easy fix for this is to add

export 
DYLD_LIBRARY_PATH="/opt/local/lib"

to your ~/.bashrc.

3. Preparing the sources

Note: The instructions for this step are identical to those on linux:

Move the tarballs to a working directory (for instance called ~/ttk) and decompress them by entering the following commands in a terminal (this assumes that you downloaded the tarballs to the ~/Downloads directory):

$ mkdir ~/ttk
$ mv ~/Downloads/ParaView-v5.5.2.tar.gz ~/ttk/
$ mv ~/Downloads/ttk-0.9.6.tar.gz ~/ttk/
$ cd ~/ttk
$ tar xvzf ParaView-v5.5.2.tar.gz
$ tar xvzf ttk-0.9.6.tar.gz

You can delete the tarballs after the source trees have been decompressed by entering the following commands:

$ rm ParaView-v5.5.2.tar.gz
$ rm ttk-0.9.6.tar.gz

4. Patching the ParaView source tree

Note: The instructions for this step are identical to those on linux:

In order to enjoy the complete set of TTK features, we recommend at this stage to patch the ParaView source tree. This step is optional. To proceed, go to the patch directory and apply it as follows:

$ cd ~/ttk/ttk-0.9.6/paraview/patch
$ ./patch-paraview-5.5.2.sh ~/ttk/ParaView-v5.5.2/

5. Configuring, building and installing ParaView

a) Configuration

To enter the configuration menu of ParaView's build, enter the following commands:

$ cd ~/ttk/ParaView-v5.5.2/
$ mkdir build
$ cd build
$ ccmake .. (on homebrew cmake there is no cmake-gui, although you can install this separately from https://cmake.org/download/)

Then, press 'c' to configure and we'll edit some CMake flags:

· CMAKE_BUILD_TYPE=Release
· PARAVIEW_ENABLE_PYTHON=ON
· VTK_SMP_IMPLEMENTATION_TYPE=Sequential

You can also enable optional pieces, including:

(i) ffmpeg:

· PARAVIEW_ENABLE_FFMPEG=ON

(ii) hdf5:

· Should be enabled by default if you installed it with homebrew

(iii) OSPRay (which requires TBB):

· PARAVIEW_USE_OSPRAY=ON
· OSPRAY_INSTALL_DIR=/opt/local/lib
· TBB_ROOT=/opt/local
(You may also have to manually set the paths for the TBB debug *.dylibs stored in /opt/local/lib (TBB_LIBRARY_DEBUG, TBB_LIBRARY_MALLOC_DEBUG, TBB_MALLOC_LIBRARY_DEBUG, and/or TBB_MALLOC_PROXY_LIBRARY_DEBUG). Occasionally, they would default to /usr/local/lib.)

(iv) TBB as the SMP implementation (which isn't necessary, but makes sense to do if you're using OSPRay):

· VTK_SMP_IMPLEMENTATION_TYPE=TBB
(changed from the default "Sequential")
· TBB_VERSION=""
(It seems the autodetected version is wrong, so we clear this out to prevent a conflict with VTK-m)
· VTKm_ENABLE_TBB=ON

(v) OpenMP as the SMP implementation (this is experimental, but useful since TTK can take advantage of it too. OSPRay will still use TBB, which is why we set TBB_ROOT in (iii)):

· VTK_SMP_IMPLEMENTATION_TYPE=OpenMP
(changed from the default "Sequential")

 · OpenMP_CXX_FLAGS="-Xpreprocessor -fopenmp 
-I/usr/local/opt/libomp/include"

· OpenMP_CXX_LIBRARY=omp

 · OpenMP_C_FLAGS="-Xpreprocessor -fopenmp 
-I/usr/local/opt/libomp/include"

· OpenMP_C_LIBRARY=omp

Then, press 'c' to configure (wait a minute) and then press 't' for advanced mode to double check the above paths and/or fill in any flags that did not appear the first time. Press 'c' again, which fills in some more paths, and then press 'c' one more time and things should be ready to press 'g' to generate and exit.

If you prefer to just run cmake as opposed to ccmake or cmake-gui, the following summarizes three possible installations:

(i) Sequential / Basic

$ cmake \

-DCMAKE_BUILD_TYPE=Release \

-DPARAVIEW_ENABLE_PYTHON=ON \

-DVTK_SMP_IMPLEMENTATION_TYPE=Sequential \

-DPARAVIEW_ENABLE_FFMPEG=ON \

..

(ii) OSPRay + TBB

$ cmake \

-DCMAKE_BUILD_TYPE=Release \

-DPARAVIEW_ENABLE_PYTHON=ON \

-DVTK_SMP_IMPLEMENTATION_TYPE=TBB \

-DTBB_VERSION="" \

-DVTKm_ENABLE_TBB=ON \

-DPARAVIEW_USE_OSPRAY=ON \

-DOSPRAY_INSTALL_DIR=/opt/local/lib \

-DTBB_ROOT=/opt/local \

-DPARAVIEW_ENABLE_FFMPEG=ON \

..

(ii) OSPRay + OpenMP

$ cmake \

-DCMAKE_BUILD_TYPE=Release \

-DPARAVIEW_ENABLE_PYTHON=ON \

-DVTK_SMP_IMPLEMENTATION_TYPE=OpenMP \

-DOpenMP_CXX_FLAGS="-Xpreprocessor -fopenmp -I/usr/local/opt/libomp/include" \

-DOpenMP_CXX_LIBRARY=omp \

-DOpenMP_C_FLAGS="-Xpreprocessor -fopenmp -I/usr/local/opt/libomp/include" \

-DOpenMP_C_LIBRARY=omp \

-DPARAVIEW_USE_OSPRAY=ON \

-DOSPRAY_INSTALL_DIR=/opt/local/lib \

-DTBB_ROOT=/opt/local \

-DPARAVIEW_ENABLE_FFMPEG=ON \

..

b) Build

Now you can start the compilation process by entering the following command, where N is the number of available cores on your system (this will take a LONG time):

$ make -jN

c) Installation

Once the build is finished, we recommend that you do not use make install. We will work directly in the build directory for the source tree instead of trying to package up a MacOS .app file in /Applications. We'll need to manually make a directory for this:

$ mkdir 
~/ttk/ParaView-v5.5.2/build/bin/paraview.app/Contents/MacOS/plugins

6. Configuring, building and installing TTK

a) Configuration

To enter the configuration menu of TTK's build, enter the following commands:

$ cd ~/ttk/ttk-0.9.6/
$ mkdir ttk_install (for installing standalone apps)
$ mkdir build
$ cd build
$ ccmake ..

The configuration window opens. Press 'c' to configure, and you'll see that it cannot yet find ParaView. First, we'll fix this:

· ParaView_DIR=~/ttk/ParaView-v5.5.2/build/
< br> Press 'c' again to configure (you can ignore the warnings). Also note that VTK_DIR should automatically be set to the homebrew installation of VTK (/usr/local/lib/cmake/vtk-8.1). Next, change:

· CMAKE_BUILD_TYPE=Release
· CMAKE_INSTALL_PREFIX=~/ttk/ttk-0.9.6/ttk_install
(this is where standalone apps and other TTK components are installed)

 · TTK_INSTALL_PLUGIN_DIR=
~/ttk/ParaView-v5.5.2/build/bin/paraview.app/Contents/MacOS/plugins

(this is where ParaView plugins are installed)

Note that you can enable building certain portions of TTK at this time as well by switching the flags associated with each (e.g. TTK_BUILD_PARAVIEW_PLUGINS, TTK_BUILD_STANDALONE_APPS, etc.). Finally, if you'd like to try out OpenMP (again, experimental), you would add:
· TTK_ENABLE_OPENMP=ON

 · OpenMP_CXX_FLAGS="-Xpreprocessor -fopenmp 
-I/usr/local/opt/libomp/include"

· OpenMP_CXX_LIB_NAMES=omp

 · OpenMP_omp_LIBRARY=/usr/local/opt/libomp/lib/libomp.
dylib

Press 'c' to reconfigure (again takes a few seconds) and then press 'g' to generate.

If you prefer to just run cmake as opposed to ccmake or cmake-gui, the following summarizes the two possible installations:

(i) Basic TTK

$ cmake \

-DParaView_DIR=~/ttk/ParaView-v5.5.2/build/ \

-DCMAKE_BUILD_TYPE=Release \

-DCMAKE_INSTALL_PREFIX=~/ttk/ttk-0.9.6/ttk_install \

-DTTK_INSTALL_PLUGIN_DIR=~/ttk/ParaView-v5.5.2/build/bin/paraview.app/Contents/MacOS/plugins \

..

(ii) TTK + OpenMP

$ cmake \

-DParaView_DIR=~/ttk/ParaView-v5.5.2/build/ \

-DCMAKE_BUILD_TYPE=Release \

-DCMAKE_INSTALL_PREFIX=~/ttk/ttk-0.9.6/ttk_install \

-DTTK_INSTALL_PLUGIN_DIR=~/ttk/ParaView-v5.5.2/build/bin/paraview.app/Contents/MacOS/plugins \

-DTTK_ENABLE_OPENMP=ON \

-DOpenMP_CXX_FLAGS="-Xpreprocessor -fopenmp -I/usr/local/opt/libomp/include" \

-DOpenMP_CXX_LIB_NAMES=omp \

-DOpenMP_omp_LIBRARY=/usr/local/opt/libomp/lib/libomp.dylib \

..

b) Build

Now you can start the compilation process by entering the following command, where N is the number of available cores on your system:

$ make -jN

c) Installation

Once the build is finished, enter the following command to install your build of TTK into your ParaView installation:

$ make install

Note that in addition to copying the TTK plugins to your ParaView installation (TTK_INSTALL_PLUGIN_DIR), the above command also installed a collection of standalone TTK programs to CMAKE_INSTALL_PREFIX. These can be used outside of ParaView, either as command line tools or VTK-based graphical user interfaces. To list them:

$ ls CMAKE_INSTALL_PREFIX/bin/*Cmd
$ ls CMAKE_INSTALL_PREFIX/bin/*Gui

Replacing CMAKE_INSTALL_PREFIX with what we used above.

Finally, to make sure the example data files are included in the right path, you have to manually copy the example data into the ParaView .app as well:

$ cd ~/ttk/ttk-0.9.6/paraview/patch/data
$ mkdir -p ~/ttk/ParaView-v5.5.2/build/bin/paraview.app/Contents/share/paraview-5.5/data
$ cp * ~/ttk/ParaView-v5.5.2/build/bin/paraview.app/Contents/share/paraview-5.5/data

7. Checking your TTK installation

If you applied all the above steps successfully (including step 4), you can now open a terminal and type the following command to load your TTK-patched ParaView:

$ cd 
~/ttk/ParaView-v5.5.2/build/bin/paraview.app/Contents/MacOS/

$ ./paraview

At this point, everything from the standard installation procedure should be accessible. Congrats!

Now, please visit our tutorial page to watch video tutorials showing how to use TTK with ParaView with concrete examples and how to use it from your own Python or C++ code or how to extend TTK by writing up your own module!