Topology ToolKit

MacOS Installation
Please find below generic instructions for the installation of TTK from sources, under MacOS.

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

If you are an advanced user and you do not wish to install ParaView (TTK's main user interface), you still have the possibility to install TTK without ParaView and VTK support (although we highly recommend to activate them).
In that case, simply download TTK as described in section 1, install the dependencies as detailed in section 2 and finally, directly jump to section 5 ("Installing TTK").
Examples showing how to use TTK libraries from your own C++ code can be found on this page.

Most users will want to activate TTK's ParaView support.

0. Disclaimer and troubleshooting

Installing software from source can be challenging (in particular under MacOS).
Since build chains can vary quite drastically from one system to another, the instructions below may require adjustments for your system.
In case of building issues, we recommend to check the following MacOS installation script examples for ParaView and TTK. We use these scripts on a daily basis for building automatically ParaView and TTK under MacOS, for the automatic tests of TTK's continuous integration.

1. Downloads

TTK builds on top of ParaView for its main user interface. Thus, you will first need to download ParaView'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

a) Required Dependencies

Using homebrew, install:
  • cmake (tested with 3.26.4)
  • qt@5 (tested with 5.15.10)
    Note, as recommended by brew, we added qt@5 to our PATH variable. The most generic way to do this is to add export PATH="$(brew --prefix qt@5)/bin:$PATH" to either your ~/.zprofile or ~/.zshrc file. You will also want to add export CMAKE_PREFIX_PATH="$(brew --prefix qt@5)/lib/cmake:$CMAKE_PREFIX_PATH" to the same file.
  • python (tested with 3.11.4)
    Note: We use python3 instead of MacOS's default python2. To map the default executable for python, please add export PATH="$(brew --prefix python)/libexec/bin/:$PATH" and export PATH="$(brew --prefix python)/bin:$PATH to either your ~/.zprofile or ~/.zshrc file. Alternatively, you may have to set paths by hand when running cmake.
  • vtk (tested with version 9.2.6)
    This required installing certain vtk dependencies, including pyqt@5, glew, etc., which should be handled seamlessly. Installing vtk will also install hdf5 as a dependency (that ParaView can make use of).
Altogether, this required the following sequence of commands:

$ brew install cmake qt@5 python vtk boost

b) Optional Dependencies

(i) OpenMP:
Using homebrew, one can also install OpenMP support for TTK (with homebrew:
  • libomp (tested with 16.0.6)
Using the command: $ brew install libomp

(ii) OSPRay/Embree:
Our continuous integration framework does call $ brew install embree, which with the above environment will install embree 4.1.0. TTK 1.3.0 is compatible with embree version 3.4 and above, but not 4 or higher, so unfortunately this will disable embree-based features in TTK. That said, if you also $ brew install ospray (which will install embree as well), you can set PARAVIEW_ENABLE_RAYTRACING at build time as described below.

(iii) TTK optional dependencies:
Finally, in order to enjoy the complete set of TTK features, we also recommend installing the following, optional TTK dependencies:
  • eigen (for scalar field design) tested with version 3.4.0 on homebrew:
    $ brew install eigen
  • graphviz (for graph drawing features) tested with version 8.0.5 on homebrew:
    $ brew install graphviz
  • qhull (for dimension reduction features, version 2020 or later):
    $ brew install qhull
  • scikit-learn for Python3 (for data reduction features, version 0.19.0 or later). Support is still experimental. We tested with version 1.3.0, installed for python3 with pip3:
    $ brew install numpy
    $ pip3 install -U scikit-learn
  • Spectra (for the computation of the eigenfunctions of the Laplace-Beltrami operator) tested with version 1.0.1 on homebrew:
    $ brew install spectra
  • sqlite (for cinema query features), tested with version 3.42.0 on homebrew:
    $ brew install sqlite
  • ZFP (for advanced compression support, version 0.5.4 or later) tested with version 1.0.0 and installed from source (see instructions),
  • zlib (for further compression support) tested with version 1.2.13 on homebrew:
    $ brew install zlib

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.13.0.tar.gz ~/ttk/
$ mv ~/Downloads/ttk-1.3.0.tar.gz ~/ttk/
$ cd ~/ttk
$ tar xvzf ParaView-v5.13.0.tar.gz
$ tar xvzf ttk-1.3.0.tar.gz

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

$ rm ParaView-v5.13.0.tar.gz
$ rm ttk-1.3.0.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-1.3.0/paraview/patch
$ ./patch-paraview-5.13.0.sh ~/ttk/ParaView-v5.13.0/

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.13.0/
$ 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 check/edit some CMake flags (you may have to press 't' to find them):
 · CMAKE_BUILD_TYPE=Release (should be the default, if not add it as a flag below)
 · Python3_EXECUTABLE should indicate the correct binary path for python by default. Unlike in previous TTK build instructions, you do not have to set PARAVIEW_ENABLE_PYTHON or verify that PARAVIEW_PYTHON_VERSION=3

You can also enable optional pieces, including:
(i) OSPRay (which requires TBB):
 · PARAVIEW_ENABLE_RAYTRACING=ON

(ii) SMP implementation:
At this time, we do not recommend building ParaView 5.13.0 with OpenMP implementations, even though TTK can take advantage of OpenMP for some of its features. The homebrew packages for libomp does appear to not be easily supported by the ParaView build chain for MacOSX. TBB, however, is supported (but not necessary). To enable TBB for ParaView:
 · VTK_SMP_IMPLEMENTATION_TYPE=TBB
 · VTKm_ENABLE_TBB=ON


After specifying the above options, 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. You may need to press 'c' again, which fills in some more paths. Once cmake is finished configuring, you should finalize everything by pressing 'g' to generate and exit.



If you prefer to just run cmake as opposed to ccmake or cmake-gui, the following summarizes possible installations:
Basic (No Optional Dependencies)
$ cmake \
-DCMAKE_BUILD_TYPE=Release \
..
(i) ParaView + OSPRay
$ cmake \
-DCMAKE_BUILD_TYPE=Release \
-DPARAVIEW_ENABLE_RAYTRACING=ON \
..
(ii) ParaView + OSPRay + TBB
$ cmake \
-DCMAKE_BUILD_TYPE=Release \
-DPARAVIEW_ENABLE_RAYTRACING=ON \
-DVTK_SMP_IMPLEMENTATION_TYPE=TBB \
-DVTKm_ENABLE_TBB=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 may take a while, possibly multiple hours):

$ 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.

Finally, to enable ParaView and pvpython to find the TTK plugins we will build, we recommend setting the environment variable PV_PLUGIN_PATH to be the location where you choose to install TTK. Note that this is different from past installations where we manually installed TTK in the build directory. Instead, these instructions will assume that you will install TTK's plugins in /usr/local/lib/plugins (the cmake variable TTK_INSTALL_PLUGIN_DIR will be set accordingly in the next step).

To set this environment variable permanently, we recommend editing whatever file you normally configure these in (e.g. ~/.zshenv) and adding the line:

export PV_PLUGIN_PATH="/usr/local/lib/plugins"

Note that, by default, our installation of ParaView will search for plugins in ~/ttk/ParaView-v5.13.0/build/bin/paraview.app/Contents/MacOS/plugins. And, by default, our installation of pvpython will search fo plugins in ~/ttk/ParaView-v5.13.0/build/bin/plugins. Setting PV_PLUGIN_PATH overrides this so that both can search for TTK in a common location. If this directory does not exist, you may need to create it as well as /usr/local/scripts.

Users may want to choose to use a different location that /usr/local/lib/plugins, although this path is consistent with where the Linux installation of TTK installs them.

For more information, see https://www.paraview.org/Wiki/ParaView/Plugin_HowTo#Using_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-1.3.0/
$ 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.13.0/build/

Press 'c' again to configure (you can ignore any warnings). Next, change:

 · CMAKE_BUILD_TYPE=Release
       (this should be the default)
 · CMAKE_INSTALL_PREFIX=~/ttk/ttk-1.3.0/ttk_install
       (this is where standalone apps and other TTK components are installed)
 · TTK_INSTALL_PLUGIN_DIR=/usr/local/lib/plugins
       (should be the default, this is where ParaView plugins are installed)

If you are an advanced user and you do not wish to activate TTK's ParaView support, set the CMake variable TTK_BUILD_PARAVIEW_PLUGINS to OFF. Examples showing how to use TTK libraries from your own VTK code can be found on this page.
Press 'c' to reconfigure (again takes a few seconds) and then press 'g' to generate.

If you are an advanced user and you do not even wish to activate TTK's VTK support, set the CMake variable TTK_BUILD_VTK_WRAPPERS to OFF. Examples showing how to use TTK libraries from your own C++ code can be found on this page.
Press 'c' to reconfigure (again takes a few seconds) and then press 'g' to generate.

If you installed the brew packages for libomp it will be automatically detected by Cmake. Note that if you are working with optional dependencies, you may also need to set certain CMake variables, including:
  • eigen should be automatically detected.
  • embree will be detected, but the version will not match and thus it will not be enabled in TTK.
  • graphviz should be automatically detected.
  • scikit-learn should be automatically enabled.
  • spectra should be automatically detected.
  • sqlite should be automatically detected.
  • Depending on where you installed it, you may have to set ZFP_DIR to the directory where you built ZFP and set TTK_ENABLE_ZFP=ON.
  • zlib should be automatically detected.

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) TTK with only the automatically detected options
$ cmake \
-DParaView_DIR=~/ttk/ParaView-v5.13.0/build/ \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=~/ttk/ttk-1.3.0/ttk_install \
-DTTK_INSTALL_PLUGIN_DIR=/usr/local/lib/plugins \
..
(ii) TTK + ZFP
$ cmake \
-DParaView_DIR=~/ttk/ParaView-v5.13.0/build/ \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=~/ttk/ttk-1.3.0/ttk_install \
-DTTK_INSTALL_PLUGIN_DIR=/usr/local/lib/plugins \
-DZFP_DIR=/Users/josh/git/github/zfp/build \
-DTTK_ENABLE_ZFP=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:

$ 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-1.3.0/paraview/patch/data
$ mkdir -p ~/ttk/ParaView-v5.13.0/build/bin/paraview.app/Contents/share/paraview-5.11/examples
$ cp * ~/ttk/ParaView-v5.13.0/build/bin/paraview.app/Contents/share/paraview-5.11/examples

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.13.0/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!