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
===
"Persistence Atlas for Critical Point Variability in Ensembles"
Guillaume Favelier, Noura Faraj, Brian Summa, Julien Tierny
IEEE Transactions on Visualization and Computer Graphics.
Proceedings of IEEE VIS 2018.


---


INSTRUCTIONS
===
The following instructions are for Unix environments (MacOS, Linux, etc.). For
Windows users, please follow the usual procedure to import a CMake project into
VisualStudio (please be careful though, important directory paths may need to
be changed for the program to run properly).


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 Boost (http://www.boost.org/) should be installed (tested
with version 1.49.0).

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

A recent version of SciPy (http://www.scipy.org/) should be installed (tested
with version 0.18.1).

A recent version of Numpy (http://www.numpy.org/) should be installed (tested
with version 1.12.1).

A recent version of Scikit-learn (http://www.scikit-learn.org/) should be
installed (tested with version 0.19.0).

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

$ apt-get update
$ apt-get install g++ cmake libboost-dev libvtk6-dev python3-dev \
  python3-numpy python3-scipy python3-sklearn paraview


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

$ mkdir build install
$ cd build

From there, enter the following commands:

$ cmake ../ttk -DCMAKE_INSTALL_PREFIX=../install

Depending on your system, you may need to tell cmake where to find
the numpy include directory by adding:
-DPYTHON_NUMPY_INCLUDE_DIR=<numpy-location>

For Ubuntu distribution such directory may be:
/usr/lib/python3/dist-packages/numpy/core/include

For Arch Linux distribution, we may need to add the following:
-DCMAKE_CXX_FLAGS=`pkg-config --cflags python3`

If you have built your own version of VTK, you can tell cmake where
to find it by adding:
-DVTK_DIR=<vtk-location>/build

Next, enter the following command to build and install:

$ 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/file/d/1PffcEKpy7YQKF0mLtube-mh-vxPeiw3-/view?usp=sharing

And extract the ZIP archive in the 'persistance-atlas' directory with:

$ unzip data.zip

Then from the directory 'persistence-atlas', enter the following command:

$ scripts/runtime.sh

The above script will compute all the outputs presented in the paper and will provide
the total time for each use-case (see the lines starting by 'real').

If you want to start only a specific use-case, do it with the following command:

for Vortex street:
$ scripts/vortexStreet.sh

for Isabella:
$ scripts/isabella.sh

for Starting vortex:
$ scripts/startingVortex.sh

for Sea Surface Height:
$ scripts/seaSurfaceHeight.sh

for Gaussians;
$ scripts/gaussians.sh

These commands will generate several VTK files that ParaView can load
and the results can be seen as scalar fields on these data sets:

The file pmb.* contains the persistence map of each ensemble member.
The file ldm.vtu corresponds to the distance matrix between the persistence maps.
The file sfp.vtp is the planar view of the ensemble.
The file(s) mcp_{min,max}.* represent(s) the mandatory critical points of each cluster.

For reference, log files for each of these scripts are available in 'persistence-atlas/log'.

To reproduce the figures:

figure 1c:
--
To visualize the planar layout of the ensemble, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/vortexStreet/sfp.vtp' and click on 'Apply'.
Then click on 'sfp.vtp' in the pipeline and choose 'ClusterIdentifier' in the 'Coloring'
section in the 'Properties' tab.

figure 1d:
--
To visualize the mandatory critical points shown in figure 1d, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/vortexStreet/mcp_max.vti'
and 'persistence-atlas/vortexStreet/mcp_min.vti' and click on 'Apply'.
Then click on 'mcp_max.vti' in the pipeline and apply from the top menu 'Filters > Common > Threshold' on the field
'maximumComponents_cluster2', use '0' as the minimum bound and '999' as the maximum bound in the 'Properties' tab.
Follow the same procedure on 'mcp_min.vti' on the field 'minimumComponents_cluster2'.
Click on the 'eye' icon in the pipeline browser in front of 'mcp_max.vti' and 'mcp_min.vti' to
remove them from the visualization.

figure 1e:
--
To visualize the mandatory critical points shown in figure 1e, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/vortexStreet/mcp_max.vti'
and 'persistence-atlas/vortexStreet/mcp_min.vti' and click on 'Apply'.
Then click on 'mcp_max.vti' in the pipeline and apply from the top menu 'Filters > Common > Threshold' on the field
'maximumComponents_cluster0', use '0' as the minimum bound and '999' as the maximum bound in the 'Properties' tab.
Follow the same procedure on 'mcp_min.vti' on the field 'minimumComponents_cluster0'.
Click on the 'eye' icon in the pipeline browser in front of 'mcp_max.vti' and 'mcp_min.vti' to
remove them from the visualization.

figure 1f:
--
To visualize the mandatory critical points shown in figure 1f, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/vortexStreet/mcp_max.vti'
and 'persistence-atlas/vortexStreet/mcp_min.vti' and click on 'Apply'.
Then click on 'mcp_max.vti' in the pipeline and apply from the top menu 'Filters > Common > Threshold' on the field
'maximumComponents_cluster3', use '0' as the minimum bound and '999' as the maximum bound in the 'Properties' tab.
Follow the same procedure on 'mcp_min.vti' on the field 'minimumComponents_cluster3'.
Click on the 'eye' icon in the pipeline browser in front of 'mcp_max.vti' and 'mcp_min.vti' to
remove them from the visualization.

figure 1g:
--
To visualize the mandatory critical points shown in figure 1g, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/vortexStreet/mcp_max.vti'
and 'persistence-atlas/vortexStreet/mcp_min.vti' and click on 'Apply'.
Then click on 'mcp_max.vti' in the pipeline and apply from the top menu 'Filters > Common > Threshold' on the field
'maximumComponents_cluster4', use '0' as the minimum bound and '999' as the maximum bound in the 'Properties' tab.
Follow the same procedure on 'mcp_min.vti' on the field 'minimumComponents_cluster4'.
Click on the 'eye' icon in the pipeline browser in front of 'mcp_max.vti' and 'mcp_min.vti' to
remove them from the visualization.

figure 1h:
--
To visualize the mandatory critical points shown in figure 1h, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/vortexStreet/mcp_max.vti'
and 'persistence-atlas/vortexStreet/mcp_min.vti' and click on 'Apply'.
Then click on 'mcp_max.vti' in the pipeline and apply from the top menu 'Filters > Common > Threshold' on the field
'maximumComponents_cluster1', use '0' as the minimum bound and '999' as the maximum bound in the 'Properties' tab.
Follow the same procedure on 'mcp_min.vti' on the field 'minimumComponents_cluster1'.
Click on the 'eye' icon in the pipeline browser in front of 'mcp_max.vti' and 'mcp_min.vti' to
remove them from the visualization.

figure 3b:
--
To visualize the persistence map shown in the figure 3b, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/gaussians/pmb.vtu'
and click on 'Apply'.
First, click on 'pmb.vtu' in the pipeline and:
To get the first row, choose any field from 'Gaussians_075' to 'Gaussians_099' in the 'Coloring'
section in the 'Properties' tab.
To get the second row choose any field from 'Gaussians_000' to 'Gaussians_024' in the 'Coloring'
section in the 'Properties' tab.
To get the last row, choose any field from 'Gaussians_025' to 'Gaussians_074' in the 'Coloring'
section in the 'Properties' tab.

figure 3c:
--
To visualize the distance matrix shown in the figure 3c, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/gaussians/ldm.vtu'
and click on 'Apply'.
Then click on 'ldm.vtu' in the pipeline and select from the top menu 'Filters > Alphabetical > Resample To Image'
and set the dimensions to '100 x 100 x 1' and click on 'Apply'. Next, select the 'ResampleToImage1' object in
the pipeline browser and choose 'DistanceMatrix' in the 'Coloring' section in the 'Properties' tab.

figure 3d:
--
To visualize the planar layout of the ensemble, follow the same procedure as the one described
in figure 1c but open the file 'persistence-atlas/gaussians/sfp.vtp' instead.

figure 3e:
--
To visualize the mandatory critical points shown in figure 3e, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/gaussians/mcp_max.vtu'
and click on 'Apply'.
Then click on 'mcp_max.vtu' in the pipeline and apply from the top menu 'Filters > Common > Threshold' on the field
'maximumComponents_cluster0', use '0' as the minimum bound and '99' as the maximum bound in the 'Properties' tab.
Next, select the 'maximumLocationLikelihood_cluster0' in the 'Coloring' section of the 'Properties' panel.
Follow the same procedure for the fields 'maximumComponents_cluster1' (with 'maximumLocationLikelihood_cluster1')
and 'maximumComponents_cluster2' (with 'maximumLocationLikelihood_cluster2').

figure 7:
--
To visualize the first persistence map shown on the right side of figure 7, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/vortexStreet/pmb.vti' and
click on 'Apply'.
Next, select the field '50.0' in the 'Coloring' section of the 'Properties' panel.

To visualize the second persistence map shown on the right side of figure 7, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/vortexStreet/pmb.vti' and
click on 'Apply'.
Next, select the field '60.1' in the 'Coloring' section of the 'Properties' panel.

To visualize the third persistence map shown on the right side of figure 7, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/vortexStreet/pmb.vti' and
click on 'Apply'.
Next, select the field '100.0' in the 'Coloring' section of the 'Properties' panel.

To visualize the fourth persistence map shown on the right side of figure 7, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/vortexStreet/pmb.vti' and
click on 'Apply'.
Next, select the field '160.0' in the 'Coloring' section of the 'Properties' panel.

To visualize the fifth persistence map shown on the right side of figure 7, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/vortexStreet/pmb.vti' and
click on 'Apply'.
Next, select the field '200.0' in the 'Coloring' section of the 'Properties' panel.

figure 8:
--
To visualize the persistence maps shown on the right side of figure 8, follow the procedure below.
For the top image:
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/isabella/pmb.vti'
and click on 'Apply'.
Click on 'pmb.vti' in the pipeline and select from the top menu 'Filters > Common > Calculator',
use 'Result1' as 'Result Array Name' and 'velocityMag_02' as the expression right under it and press the 'Apply' button.
Now, select 'Result1' in the 'Coloring' section and 'Volume' in 'Representation' section.

For the middle image:
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/isabella/pmb.vti'
and click on 'Apply'.
Click on 'pmb.vti' in the pipeline and select from the top menu 'Filters > Common > Calculator',
use 'Result2' as 'Result Array Name' and 'velocityMag_30' as the expression right under it and press the 'Apply' button.
Now, select 'Result2' in the 'Coloring' section and 'Volume' in 'Representation' section.
You may need to modify the color transfer function in the 'Color Map Editor' of ParaView to get the exact same result.

For the bottom image:
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/isabella/pmb.vti'
and click on 'Apply'.
Click on 'pmb.vti' in the pipeline and select from the top menu 'Filters > Common > Calculator',
use 'Result3' as 'Result Array Name' and 'velocityMag_48' as the expression right under it and press the 'Apply' button.
Now, select 'Result3' in the 'Coloring' section and 'Volume' in 'Representation' section.
You may need to modify the color transfer function in the 'Color Map Editor' of ParaView to get the exact same result.

figure 9d:
--
To visualize the distance matrix shown in the figure 9d, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/startingVortex/ldm.vtu'
and click on 'Apply'.
Then click on 'ldm.vtu' in the pipeline and select from the top menu 'Filters > Alphabetical > Resample To Image'
and set the dimensions to '12 x 12 x 1' and click on 'Apply'. Next, select the 'ResampleToImage1' object in the pipeline
browser and choose 'DistanceMatrix' in the 'Coloring' section in the 'Properties' tab.

figure 9e:
--
To visualize the persistence maps shown on the right side of figure 9, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/startingVortex/pmb.vti'
and click on 'Apply'.
First, click on 'pmb.vti' in the pipeline and choose 'vorticity_angle_02' (figure 9e)
in the 'Coloring' section in the 'Properties' tab.

figure 9f:
--
To visualize the persistence maps shown on the right side of figure 9, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/startingVortex/pmb.vti'
and click on 'Apply'.
First, click on 'pmb.vti' in the pipeline and choose 'vorticity_angle_38' (figure 9f)
in the 'Coloring' section in the 'Properties' tab.

figure 10(middle):
--
To visualize the planar layout of the ensemble, follow the same procedure as the one described
in figure 1c but open the file 'persistence-atlas/startingVortex/sfp.vtp' instead.

figure 10(right):
--
To visualize the mandatory critical points shown in figure 10 (right), follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/startingVortex/mcp_max.vti'
and click on 'Apply'.
Then click on 'mcp_max.vti' in the pipeline and apply from the top menu 'Filters > Common > Threshold' on the field
'maximumComponents_cluster0', use '0' as the minimum and maximum bound in the 'Properties' tab.
Click on the 'eye' icon in the pipeline browser in front of 'mcp_max.vti' to remove it from the visualization.
Next, select the 'maximumLocationLikelihood_cluster0' in the 'Coloring' section of the 'Properties' panel.
Follow the same procedure for the field 'maximumComponents_cluster1' (with 'maximumLocationLikelihood_cluster1').

figure 11b:
--
To visualize the planar layout of the ensemble, follow the same procedure as the one described in figure 1c but
open the file 'persistence-atlas/isabella/sfp.vtp' instead.
To visualize the mandatory critical points, start ParaView, select 'File > Open' and choose the file
'persistence-atlas/isabella/mcp_max.vti' and click on 'Apply'.
Then click on 'mcp_max.vti' in the pipeline and apply from the top menu 'Filters > Common > Threshold' on the field
'maximumComponents_cluster0', use '0' as the minimum and maximum bound in the 'Properties' tab.
Follow the same procedure for the fields 'maximumComponents_cluster1' and 'maximumComponents_cluster2'.

figure 12b:
--
To visualize the planar layout of the ensemble, follow the same procedure as the one described in figure 1c but
open the file 'persistence-atlas/seaSurfaceHeight/sfp.vtp' instead.

figure 12c,12d,12e,12f:
--
To visualize the mandatory critical points, follow the procedure below.
Start ParaView, select 'File > Open' and choose the file 'persistence-atlas/seaSurfaceHeight/mcp_max.vti'
and click on 'Apply'.
Then click on 'mcp_max.vti' in the pipeline and apply from the top menu 'Filters > Common > Threshold' on the field
'maximumComponents_cluster0', use '0' as the minimum bound and '9999' as the maximum bound in the 'Properties' tab.
Next, select the 'maximumLocationLikelihood_cluster0' in the 'Coloring' section of the 'Properties' panel.
Click on the 'eye' icon in the pipeline browser in front of 'mcp_max.vti' to remove it from the visualization.
You can iterate on the clusters by changing the name of the fields used by the threshold
from '*_cluster0', '*_cluster1', '*_cluster2' and '*_cluster3' (corresponding to figure 12f, figure 12d, figure 12e
and figure 12c respectively).


4) Program options and arguments:
==
From the directory "PersistenceAtlas/install", running the following command line will
display the program options and arguments:

$ ./bin/persistenceAtlasCmd -h
[Common]  _____ _____ _  __                       __  __    ____   ___  _  ___
[Common] |_   _|_   _| |/ /                      / /__\ \  |___ \ / _ \/ |( _ )
[Common]   | |   | | | ' /                      | |/ __| |   __) | | | | |/ _ \
[Common]   | |   | | | . \                      | | (__| |  / __/| |_| | | (_) |
[Common]   |_|   |_| |_|\_\                     | |\___| | |_____|\___/|_|\___/
[Common]                                         \_\  /_/
[Common] Welcome!
[CommandLine] Missing mandatory argument:
[CommandLine]   -i <{Input data-sets (*.vti, *vtu, *vtp)}>
[CommandLine]
[CommandLine] Usage:
[CommandLine]   ./bin/persistenceAtlasCmd
[CommandLine] Argument(s):
[CommandLine]   [-d <Global debug level (default: 3)>]
[CommandLine]   [-t <Thread number (default: 16)>]
[CommandLine]   [-numberOfClusters <Force number of clusters (-1 for auto-detection) (default: -1)>]
[CommandLine]   [-critical <Critical point type (0: min, 1: max, 2: both) (default: 1)>]
[CommandLine]   [-threshold <Persistence threshold (default: 0.01)>]
[CommandLine]   [-spread <Persistence spread (standard deviation) (default: 0.1)>]
[CommandLine]   [-numberOfNeighbors <Number Of Neighbors (default: 5)>]
[CommandLine]   [-mcpThreshold <Persistence threshold in MandatoryCriticalPoints module (default: 0)>]
[CommandLine]   -i <{Input data-sets (*.vti, *vtu, *vtp)}>
[CommandLine]   [-o <Output file name base (no extension) (default: `output')>]
[CommandLine] Option(s):


5) Using other data-sets:
==
These plugins use VTK Unstructured Grid (vtu) or VTK Image Data (vti) files.
In the case of an image data, an implicit triangulation is built.

The scalar fields must be associated to the points.