Skip to content
No description, website, or topics provided.
C++ CMake Shell Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
scripts
ttk
LICENSE
README

README

DATA DISCLAIMER
===
The data sets contained in this archive are the property of their copyright owners. They are made available in this archive for research purpose only. They should not be redistributed publicly without their owner's permission.


CODE DISCLAIMER
===
This code is provided "as is" without warranty of any kind. It is made available under the licensing terms described in the file 'LICENSE'.


RELATED PUBLICATION
===
"Progressive Wasserstein Barycenters of Persistence Diagrams"
Jules Vidal, Joseph Budin, Julien Tierny
IEEE Transactions on Visualization and Computer Graphics.
Proceedings of IEEE VIS 2019.


---


INSTRUCTIONS
===
The following instructions are for Ubuntu 18.04 LTS


1) Software requirements:
==
This code requires the VTK development libraries to be installed on the system (version 6.1 or higher). Please see http://www.vtk.org/ for installation instructions.

A recent version of ParaView (http://www.paraview.org) should be installed (tested with version 5.4.1).

A recent version of CMake (http://www.cmake.org) should be installed (tested with version 2.8).

A recent version of Python (http://www.python.org/) should be installed (tested with version 3.6.3).


Assuming that a Ubuntu 18.04 system is used, enter the following commands to install the required dependencies:

$ sudo apt-get update
$ sudo apt-get install g++ cmake-qt-gui libvtk6-dev python3-dev \
  python3-numpy paraview


2) Compiling the code:
==
Enter the 'wasserstein-pd-barycenter' directory and type the following command (omit the "$" character):

$ mkdir build install
$ cd build

From there, enter the following commands:

$ cmake-gui ../ttk 

The configuration windows opens. Proceed as follows :
1. Click on the "Configure" button. Use the default settings in the pop-up window.
2. After configuration, make sure that the following variables are set as follows :  
  * CMAKE_INSTALL_PREFIX = `../install`
  * TTK_BUILD_PARAVIEW_PLUGINS = OFF
  * TTK_BUILD_STANDALONE_APPS = ON
3. Click on the "Generate" button and close the configuration window when the generation is completed.

In order to build the project, enter the following command, where `N` is the number of available cores on your system (this will take a **LONG** time):
```bash
$ make -jN
```
Once the build is finished, enter the following command to install the project in the *install* folder:
```bash
$ make install

3) Reproducing the results from the paper:
==
Download the ZIP archive from the following website (please use a web browser):
https://drive.google.com/open?id=1fxPAUmYT4UAUHh7K0w83znckyw_NTLan

And extract the ZIP archive in the 'wasserstein-pd-barycenter' directory with:

$ unzip data.zip

You are now able to reproduce the different results of the paper. Go to the scripts/ folder :

$ cd scripts/

Tables
_____________

To reproduce the tables :

Go to the tables/ folder and run each one of the following scripts to print
the content of tables 1, 2 and 3. 
$ cd tables/
$ ./table1.sh
$ ./table2.sh
$ ./table3.sh

Figure 1.f
-------------
To reproduce the clustering output of figure 1.f, go to the fig1f/ folder and run the script:

$ cd fig1f
$ ./fig1f.sh

This will run the algorithm and output the results as .vtu files in the vtu_outputs/ folder.
The resulting clustering can be read in the console output. The *isabel* data-set counts 12 members in 3 equal clusters. As the persistence diagrams are indexed in this order, a correct clustering is thus :
```
Cluster 0 : [0, 1, 2, 3]
Cluster 1 : [8, 9, 10, 11]
Cluster 2 : [4, 5, 6, 7]
```

To visualize the results, run the attached ParaView state, according to your version (5.4 or higher):

$ paraview --state=./fig1f_5.4.pvsm


Figure 5
-------------
To reproduce figure 5, go to the fig5/ folder and run the script:

$ cd fig5
$ ./fig5.sh

This will run the algorithm and output the results as .vtu files in the vtu_outputs/ folder.
To visualize the results, run the attached ParaView state, according to your version (5.4 or higher):

$ paraview --state=./fig5_5.4.pvsm


Figure 6
-------------
To reproduce the orange curve of figure 6, go to the fig6/ folder and run the script:

$ cd fig6
$ ./fig6.sh

This will run the algorithm and output the data : the energy.txt file contains the energy values and associated time values. The data may be plotted with python : 
$ python fig6.py


Figure 7
-------------
To reproduce figure 7, go to the fig7/ folder and run the script:

$ cd fig7
$ ./fig7.sh

This will run the algorithm and output the results as .vtu files in the vtu_outputs/ folder.
To visualize the results, run the attached ParaView state, according to your version (5.4 or higher):

$ paraview --state=./fig7_5.4.pvsm


Figure 8
-------------
To reproduce figure 8, go to the fig8/ folder and run the script:

$ cd fig8
$ ./fig8.sh

This will run the algorithm and output the results as .vtu files in the vtu_outputs/ folder.
The resulting clustering can be read in the console output. The *gaussians* data-set contains 100 members dispatched in 3 clusters : 25 for the first cluster, 50 for the second cluster and 25 for the third. As the persistence diagrams are indexed in this order, the right clustering is the following :

Cluster 0 : [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24]
Cluster 1 : [25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74]
Cluster 2 : [75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99]


To visualize the results, run the attached ParaView state, according to your version (5.4 or higher):

$ paraview --state=./fig8_5.4.pvsm


Figure 9
-------------
To reproduce figure 9, go to the fig9/ folder and run the script:

$ cd fig9
$ ./fig9.sh

This will run the algorithm and output the results as .vtu files in the vtu_outputs/ folder.
The vortexStreet data-set contains 45 members for 5 clusters. An example of a correct clustering is :

Cluster 0 : [0, 1, 2, 3, 4, 5, 6, 7, 8]
Cluster 1 : [27, 28, 29, 30, 31, 32, 33, 34, 35]
Cluster 2 : [18, 19, 20, 21, 22, 23, 24, 25, 26]
Cluster 3 : [36, 37, 38, 39, 40, 41, 42, 43, 44]
Cluster 4 : [9, 10, 11, 12, 13, 14, 15, 16, 17]


To visualize the results, run the attached ParaView state, according to your version (5.4 or higher):

$ paraview --state=./fig9_5.4.pvsm


Figure 10
-------------
To reproduce figure 10, go to the fig10/ folder and run the script:

$ cd fig10
$ ./fig10.sh

This will run the algorithm and output the results as .vtu files in the vtu_outputs/ folder.
The startingVortex data-set contains 12 members for 2 clusters. The expected output of the clustering is :

Cluster 0 : [0, 1, 2, 3, 4, 5]
Cluster 1 : [6, 7, 8, 9, 10, 11]


To visualize the results, run the attached ParaView state, according to your version (5.4 or higher):

$ paraview --state=./fig10_5.4.pvsm


Figure 11
-------------
To reproduce figure 11, go to the fig11/ folder and run the script:

$ cd fig11
$ ./fig11.sh

This will run the algorithm and output the results as .vtu files in the vtu_outputs/ folder.
The seaSurfaceHeight contains 48 members, dispatched in 4 clusters. A correct clustering is :

Cluster 0 : [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
Cluster 1 : [24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35]
Cluster 2 : [36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47]
Cluster 3 : [12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]


To visualize the results, run the attached ParaView state, according to your version (5.4 or higher):

$ paraview --state=./fig11_5.4.pvsm


Timings
-------------
The additionnal script script/timings.sh runs all the experiments providing timing results, namely the content of tables 1 and 2. Attached is the output of this script run on our desktop computer, with its specifications.


4) Program options and arguments:
==
The above installation have provided you with two executables files : ttkPersistenceDiagramsBarycenterCmd and ttkPersistenceDiagramsClusteringCmd, available in `install/bin/` 
You can directly use those in order to try out our implementation of our method.


In order to be able to execute them, you will have to link the libraries.
For instance from the main repository :

$ export LD_LIBRARY_PATH="`pwd`/install/lib/ttk"

Then, simply entering one of those commands should list you the needed parameters.
For the barycenter computation : 

$ ./install/bin/ttkPersistenceDiagramsBarycenterCmd 
[CommandLine] Missing mandatory argument:
[CommandLine]   -i <{Input data-sets (*.vti, *vtu, *vtp)}>
[CommandLine]
[CommandLine] Usage:
[CommandLine]   ttkPersistenceDiagramsBarycenterCmd
[CommandLine] Argument(s):
[CommandLine]   [-d <Global debug level (default: 3)>]
[CommandLine]   [-t <Global thread number (default: 16)>]
[CommandLine]   [-G <geometry (default: 1)>]
[CommandLine]   [-M <algorithm : 0= prog PB, 2=Auction (default: 0)>]
[CommandLine]   [-plot <computes and outputs the real cost evolution (default: 0)>]
[CommandLine]   [-P <use progressive computation (default: 1)>]
[CommandLine]   [-T <Time Limit for Computation, in seconds. No time limit by default (default: -1)>]
[CommandLine]   -i <{Input data-sets (*.vti, *vtu, *vtp)}>
[CommandLine]   [-o <Output file name base (no extension) (default: `output')>]
[CommandLine] Option(s):

For the clustering computation : 

$ ./install/bin/ttkPersistenceDiagramsClusteringCmd
[CommandLine] Missing mandatory argument:
[CommandLine]   -i <{Input data-sets (*.vti, *vtu, *vtp)}>
[CommandLine]
[CommandLine] Usage:
[CommandLine]   ttkPersistenceDiagramsClusteringCmd
[CommandLine] Argument(s):
[CommandLine]   [-d <Global debug level (default: 3)>]
[CommandLine]   [-t <Global thread number (default: 16)>]
[CommandLine]   [-P <Set the type of critical pairs considered in the clustering.
                        -1 : all critical pairs
                         0 : only min-saddle pairs
                         1 : onlysaddle-saddle pairs
                         2 : only saddle-max pairs
                 (default: -1)>]
[CommandLine]   [-A <Use the kmean acceleration (default: 1)>]
[CommandLine]   [-I <Use the kmeanspp init. (default: 1)>]
[CommandLine]   [-K <Number of Clusters (default: 1)>]
[CommandLine]   [-T <Time Limit for Computation, in seconds. No time limit by default (default: -1)>]
[CommandLine]   [-G <Geometry Penalization, bet 0. and 1., 1. means no lifting (default: 1)>]
[CommandLine]   -i <{Input data-sets (*.vti, *vtu, *vtp)}>
[CommandLine]   [-o <Output file name base (no extension) (default: `output')>]
[CommandLine] Option(s):


A standard exemple for the barycenter computation of two persistence diagrams within 1 second and minimal verbosity is :

$ ./install/bin/ttkPersistenceDiagramsBarycenterCmd -i diagram1.vtu -i diagram2.vtu -o output_barycenter -T 1 -d 1 


Look at the provided scripts for more examples on how to use those commands.


6) Using your own data :
==

If you want to test our approach on your own data, you will need to pre-compute the persistence diagrams.
For this purpose, we provide the implementation of Gueunet et al., available in the Topology ToolKit (https://topology-tool-kit.github.io/).

Note that your data must be in a *.vtu* or *.vti* format.

Simply use the ttkPersistenceDiagramCmd command as so :

$ ./install/bin/ttkPersistenceDiagramCmd  -i your_vtu_or_vti_data_file -o output_diagram.vtu -F your_scalarField_index_in_the_data
You can’t perform that action at this time.