Build TTK as standalone libraries and programs without ParaView

[Julien Tierny]

Dear all,

I've been asked recently if it was possible to run quickly TTK without installing ParaView for time performance bench-marking. The answer is yes :)

Please find below my answer that I post here for archiving purposes.
I will update the installation instructions accordingly.

Cheers,

most TTK modules come with automatically generated standalone programs (command line or vtk-gui based) that were designed for that precise purpose.

I describe below how to install and run the FTM standalone for a linux-style environment.

first, download the latest version of the source code:
$ git clone https://github.com/topology-tool-kit/ttk.git
the FTM standalone available in the latest version of TTK (0.9.7) was in a legacy format which I fixed yesterday and the remainder of these notes are valid for the git master version of the code.

next, to build TTK without paraview:
$ cd ttk
$ mkdir build
$ cd build
$ cmake ../ -DTTK_BUILD_PARAVIEW_PLUGINS=OFF
$ make -jN

where N is the number of available cores on your system.

this will build the entire topology toolkit, at the exception of the paraview layer.
note that a recent version of VTK must be installed on your system at this point (8.1 or later).
if cmake failed at finding your VTK installation path, you can enter it with the cmake variable VTK_DIR.
the default installation path on linux is "/usr/local" (you may want to adjust it, cmake variable CMAKE_INSTALL_PREFIX).

next, you can install ttk:
$ make install
(note that depending on your install dir and user privileges, you may need to add "sudo" before make).

at this point ttk is installed. by default, all standalone apps are installed in /usr/local/bin. for most linux systems, this directory is included in the path variable so you can invoke ttk programs directly or use the explicit full path, for instance:
$ /usr/local/bin/ttkFTMTreeCmd

by default, this command returns the following help message:
[Common] _____ _____ _ __ __ __ ____ ___ _ ___
[Common] |_ _|_ _| |/ / / /__\ \ |___ \ / _ \/ |/ _ \
[Common] | | | | | ' / | |/ __| | __) | | | | | (_) |
[Common] | | | | | . \ | | (__| | / __/| |_| | |\__, |
[Common] |_| |_| |_|\_\ | |\___| | |_____|\___/|_| /_/
[Common] \_\ /_/
[Common] Welcome!
[CommandLine] Missing mandatory argument:
[CommandLine] -i <{Input data-sets (*.vti, *vtu, *vtp)}>
[CommandLine]
[CommandLine] Usage:
[CommandLine] ttkFTMTreeCmd
[CommandLine] Argument(s):
[CommandLine] [-d <Global debug level (default: 3)>]
[CommandLine] [-t <Thread number (default: 4)>]
[CommandLine] [-f <Field identifier (default: 0)>]
[CommandLine] [-T <Tree type {0: JT, 1: ST, 2: CT} (default: 0)>]
[CommandLine] -i <{Input data-sets (*.vti, *vtu, *vtp)}>
[CommandLine] [-o <Output file name base (no extension) (default: `output')>]
[CommandLine] Option(s):

to run it, you must specify as an input a valid VTK file: either VTI (which are implicitly and efficiently triangulated by ttk), VTU or VTP. our implementation supports 2D or 3D grids/triangulations. if you are using a VTU or VTP file, please make sure it is a valid simplicial complex (i.e. triangle-only mesh in 2D, tet-only mesh in 3D).

the program will process scalar fields defined as point data arrays.
you can use the option "-f" to specify which scalar field to consider in case you have several.
you can also specify the type of tree that you want to compute with the option "-T": 0 for join trees (i.e. with minima), 1 for split trees (with maxima) and 2 for contour trees.
by default, join trees are computed.

by default, the program will use a number of threads equal to the number of available logical CPU cores on your system. my laptop is a hyperthreaded dual core, so by default, ttk uses 4 threads.

when you launch the program on a VTK file, it will load the file, compute the required tree and store all the output of the TTK module to disk.

for instance, if you consider the dataset "ctBones.vti" (which is available in the ttk-data repository: https://github.com/topology-tool-kit/ttk-data), you can run the program as follows:

$ ttkFTMTreeCmd -i ctBones.vti

here is the output I get on my laptop:
[Common] _____ _____ _ __ __ __ ____ ___ _ ___
[Common] |_ _|_ _| |/ / / /__\ \ |___ \ / _ \/ |/ _ \
[Common] | | | | | ' / | |/ __| | __) | | | | | (_) |
[Common] | | | | | . \ | | (__| | / __/| |_| | |\__, |
[Common] |_| |_| |_|\_\ | |\___| | |_____|\___/|_| /_/
[Common] \_\ /_/
[Common] Welcome!
[ttkProgramBase] Reading input data...
Generic Warning: In /var/tmp/portage/sci-libs/vtk-8.1.0-r2/work/VTK-8.1.0/Common/Core/vtkInstantiator.cxx, line 265
vtkInstantiator::CreateInstance was deprecated for VTK 8.1 and will be removed in a future version.

[ttkProgramBase] done! (read 16777216 vertices, 16581375 cells)
[ImplicitTriangulation] The getVertex*() requests are accelerated.
Launch on field : Scalars_
[FTM] ------------
[FTM] number of threads : 4
[FTM] * debug lvl : 3
[FTM] * tree type : Join
[FTM] ------------
[FTM] alloc in 0.317132
[FTM] init in 0.058888
[FTM] sort step in 1.18297
[FTM] leafSearch JT in 2.51529
[FTM] leafGrowth JT in 1.17465
[FTM] trunk JT in 0.475229
[FTM] merge trees in 4.16561
[FTM] build tree in 4.16568
[FTM] Total in 5.40772
[ttkFTMTree] Memory usage: 575.632 MB.
[ttkProgramBase] Saving output file `output_port#0.vtu'...
[ttkProgramBase] Saving output file `output_port#1.vtu'...
[ttkProgramBase] Saving output file `output_port#2.vti'...
[Common] Goodbye

the precise timing of the algorithm is given by the line:
"[FTM] Total in 5.40772"

to change the number of threads, simply use the "-t" option, such as (for a sequential execution in this example):
$ ttkFTMTreeCmd -i ctBones.vti -t 1
[Common] _____ _____ _ __ __ __ ____ ___ _ ___
[Common] |_ _|_ _| |/ / / /__\ \ |___ \ / _ \/ |/ _ \
[Common] | | | | | ' / | |/ __| | __) | | | | | (_) |
[Common] | | | | | . \ | | (__| | / __/| |_| | |\__, |
[Common] |_| |_| |_|\_\ | |\___| | |_____|\___/|_| /_/
[Common] \_\ /_/
[Common] Welcome!
[ttkProgramBase] Reading input data...
Generic Warning: In /var/tmp/portage/sci-libs/vtk-8.1.0-r2/work/VTK-8.1.0/Common/Core/vtkInstantiator.cxx, line 265
vtkInstantiator::CreateInstance was deprecated for VTK 8.1 and will be removed in a future version.

[ttkProgramBase] done! (read 16777216 vertices, 16581375 cells)
[ImplicitTriangulation] The getVertex*() requests are accelerated.
Launch on field : Scalars_
[FTM] ------------
[FTM] number of threads : 1
[FTM] * debug lvl : 3
[FTM] * tree type : Join
[FTM] ------------
[FTM] alloc in 0.326278
[FTM] init in 0.0651619
[FTM] sort step in 2.47898
[FTM] leafSearch JT in 4.49645
[FTM] leafGrowth JT in 1.85332
[FTM] trunk JT in 0.731497
[FTM] merge trees in 7.08138
[FTM] build tree in 7.08142
[FTM] Total in 9.62561
[ttkFTMTree] Memory usage: 551.451 MB.
[ttkProgramBase] Saving output file `output_port#0.vtu'...
[ttkProgramBase] Saving output file `output_port#1.vtu'...
[ttkProgramBase] Saving output file `output_port#2.vti'...
[Common] Goodbye

note that the memory evaluation is highly inaccurate (based on the proc filesystem under linux) and should not be considered for performance measurement.

as mentioned before, the program will generate one file per output of the TTK filter:
- output_port#0.vtu: a point cloud representing the critical notes of the tree (with extra data)
- output_port#1.vtu: the arcs of the tree (with extra data)
- output_port#2.vti: the segmentation of the input data, where the field "SegmentationId" refers for each mesh vertex to the arc it maps to in the output tree.

note that this program does not perform topological simplification. for this, you need to combine several ttk modules, as described in this example:
https://github.com/topology-tool-kit/ttk/tree/master/examples/vtk-c%2B%2B

note that the FTM algorithm is specifically designed to compute *augmented* trees (i.e. containing the degree-2 regular nodes in the inside of each arc, corresponding to regular vertices) for data segmentation applications, such as the one demoed here:
https://topology-tool-kit.github.io/img/gallery/ctBones.jpg
therefore, it is possible (although we don't know) that it may be slower than non-augmented algorithms.
also, this algorithm targets a workstation usage, and is tailored for multi-CPU-core shared memory parallelism and hence favors coarse grain parallelism (i.e. parallel efficiency will eventually decrease with a high number of cores).

finally, note that we've just had a recent extension of this approach that has been accepted to the IEEE Transactions on Parallel and Distributed Systems, which significantly improves the performance of FTM.
the implementation of the extended algorithm should be integrated to TTK by the end of February (hopefully).
--
Dr Julien Tierny
CNRS Researcher
Sorbonne Universite
http://lip6.fr/Julien.Tierny