Path Mappings and Branch Mappings in MergeTreeBarycenter and MergeTreeDistanceMatrtix

README

@@ -304,3 +304,10 @@ Data specs
   "acknowledgement": "Berk Geveci, Christoph Garth, Garrett Aldrich, and Jonas Lukasczyk",
   "url": "https://jluk.de/resources/papers/NestedTrackingGraphs2017.pdf"
 }
+
+{
+  "name": "bdied_outlier/",
+  "description": "A synthetic dataset that highlights the advantages of branch decomposition-independent edit distances for merge trees. It is a simplified version of the one generated for the experiments in this paper: https://doi.org/10.1111/cgf.14547",
+  "acknowledgement": "Florian Wetzels, Heike Leittge, and Christoph Garth",
+  "url": "https://github.com/scivislab/BDI-ED/tree/main/test_datasets/branchVSconstrained_outlier"
+}

bdied_outlier/outlier.vtm

@@ -0,0 +1,14 @@
+<VTKFile type="vtkMultiBlockDataSet" version="1.0" byte_order="LittleEndian" header_type="UInt64">
+  <vtkMultiBlockDataSet>
+    <DataSet index="0" file="outlier/outlier_0_0.vti"/>
+    <DataSet index="1" file="outlier/outlier_1_0.vti"/>
+    <DataSet index="2" file="outlier/outlier_2_0.vti"/>
+    <DataSet index="3" file="outlier/outlier_3_0.vti"/>
+    <DataSet index="4" file="outlier/outlier_4_0.vti"/>
+    <DataSet index="5" file="outlier/outlier_5_0.vti"/>
+    <DataSet index="6" file="outlier/outlier_6_0.vti"/>
+    <DataSet index="7" file="outlier/outlier_7_0.vti"/>
+    <DataSet index="8" file="outlier/outlier_8_0.vti"/>
+    <DataSet index="9" file="outlier/outlier_9_0.vti"/>
+  </vtkMultiBlockDataSet>
+</VTKFile>

docs/mergeTreeBarycenter_branchMapping.md

@@ -0,0 +1,49 @@
+# Merge Tree Barycenter with Branch Mapping 
+
+![Branch Mapping and Distance Matrix example Image]()
+
+## Pipeline description
+This example first loads a multi block of scalar fields from disk.
+Then, the Split Tree is computed on each scalar field using the [MergeTree](https://topology-tool-kit.github.io/doc/html/classttkMergeTree.html) module.
+
+All these trees are passed to [MergeTreeClustering](https://topology-tool-kit.github.io/doc/html/classttkMergeTreeClustering.html). It computes the distance and corresponding mapping between the first two trees in the metric space of merge trees defined by the branch mapping distance (thus, the underlying metric to the branch mapping distance). The [MergeTreeClustering](https://topology-tool-kit.github.io/doc/html/classttkMergeTreeClustering.html) module only computes one distance and one mapping because the actual barycenter computation is not possible with this metric.
+
+In addition, a distance matrix for the input trees is computed with [MergeTreeDistanceMatrix](https://topology-tool-kit.github.io/doc/html/classttkMergeTreeDistanceMatrix.html).
+
+The python script computes the branch mapping distance and saves the resulting mapping as well as the distance matrix in form of a table. The paraview state file additionally renders the matrix as a heatmap.
+
+## ParaView
+To reproduce the above screenshots, go to your [ttk-data](https://github.com/topology-tool-kit/ttk-data) directory and enter the following command:
+``` bash
+paraview states/mergeTreeBarycenter_branchMapping.pvsm
+```
+
+## Python code
+
+``` python  linenums="1"
+--8<-- "python/mergeTreeBarycenter_branchMapping.py"
+```
+
+To run the above Python script, go to your [ttk-data](https://github.com/topology-tool-kit/ttk-data) directory and enter the following command:
+``` bash
+pvpython python/mergeTreeBarycenter_branchMapping.py
+```
+
+
+## Inputs
+- [outlier.vtm](https://github.com/topology-tool-kit/ttk-data/tree/dev/bdied_outlier/outlier.vtm): a vtk multiblock containing 10 regular grids.
+
+## Outputs
+-  `merge_tree_mapping.vtm`: the computed branch mapping as a vtk multiblock.
+-  `distance_matrix.csv`: the distance matrix as a csv table.
+
+
+## C++/Python API
+[BlockAggregator](https://topology-tool-kit.github.io/doc/html/classttkBlockAggregator.html)
+
+[MergeTree](https://topology-tool-kit.github.io/doc/html/classttkMergeTree.html)
+
+[MergeTreeClustering](https://topology-tool-kit.github.io/doc/html/classttkMergeTreeClustering.html)
+
+[MergeTreeDistanceMatrix](https://topology-tool-kit.github.io/doc/html/classttkMergeTreeDistanceMatrix.html)
+

docs/mergeTreeBarycenter_pathMapping.md

@@ -0,0 +1,49 @@
+# Merge Tree Barycenter with Path Mapping 
+
+![Path Mapping Barycenter and Distance Matrix example Image]()
+
+## Pipeline description
+This example first loads a multi block of scalar fields from disk.
+Then, the  the Split Tree is computed on each scalar field using the [MergeTree](https://topology-tool-kit.github.io/doc/html/classttkMergeTree.html) module.
+
+All these trees are passed to [MergeTreeClustering](https://topology-tool-kit.github.io/doc/html/classttkMergeTreeClustering.html) to compute a barycenter in the metric space of merge trees defined by the path mapping distance (thus, the number of clusters has to be set to one and the underlying metric to the path mapping distance). 
+
+In addition, a distance matrix for the input trees is computed with [MergeTreeDistanceMatrix](https://topology-tool-kit.github.io/doc/html/classttkMergeTreeDistanceMatrix.html).
+
+The python script computes the barycenter and saves the resulting planar layout as well as the distance matrix in form of a table. The paraview state file additionally renders the matrix as a heatmap.
+
+## ParaView
+To reproduce the above screenshots, go to your [ttk-data](https://github.com/topology-tool-kit/ttk-data) directory and enter the following command:
+``` bash
+paraview states/mergeTreeBarycenter_pathMapping.pvsm
+```
+
+## Python code
+
+``` python  linenums="1"
+--8<-- "python/mergeTreeBarycenter_pathMapping.py"
+```
+
+To run the above Python script, go to your [ttk-data](https://github.com/topology-tool-kit/ttk-data) directory and enter the following command:
+``` bash
+pvpython python/mergeTreeBarycenter_pathMapping.py
+```
+
+
+## Inputs
+- [outlier.vtm](https://github.com/topology-tool-kit/ttk-data/tree/dev/bdied_outlier/outlier.vtm): a vtk multiblock containing 10 regular grids.
+
+## Outputs
+-  `merge_tree_barycenter.vtm`: the computed barycenter merge tree as a vtk multiblock.
+-  `distance_matrix.csv`: the distance matrix as a csv table.
+
+
+## C++/Python API
+[BlockAggregator](https://topology-tool-kit.github.io/doc/html/classttkBlockAggregator.html)
+
+[MergeTree](https://topology-tool-kit.github.io/doc/html/classttkMergeTree.html)
+
+[MergeTreeClustering](https://topology-tool-kit.github.io/doc/html/classttkMergeTreeClustering.html)
+
+[MergeTreeDistanceMatrix](https://topology-tool-kit.github.io/doc/html/classttkMergeTreeDistanceMatrix.html)
+

python/mergeTreeBarycenter_branchMapping.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python
+# state file generated using paraview version 5.10.1
+
+#### import the simple module from the paraview
+from paraview.simple import *
+
+# ----------------------------------------------------------------
+# setup the data processing pipelines
+# ----------------------------------------------------------------
+
+# create a new 'XML MultiBlock Data Reader'
+outliervtm = XMLMultiBlockDataReader(FileName=["bdied_outlier/outlier.vtm"])
+
+# create a new 'TTK MergeTree'
+tTKMergeandContourTreeFTM1 = TTKMergeTree(Input=outliervtm)
+tTKMergeandContourTreeFTM1.ScalarField = ["POINTS", "test"]
+tTKMergeandContourTreeFTM1.TreeType = "Split Tree"
+tTKMergeandContourTreeFTM1.UseAllCores = 0
+
+# create a new 'TTK BlockAggregator'
+tTKBlockAggregator1 = TTKBlockAggregator(
+    Input=[
+        tTKMergeandContourTreeFTM1,
+        OutputPort(tTKMergeandContourTreeFTM1, 1),
+        OutputPort(tTKMergeandContourTreeFTM1, 2),
+    ]
+)
+tTKBlockAggregator1.FlattenInput = 0
+
+# create a new 'TTK MergeTreeDistanceMatrix'
+tTKMergeTreeDistanceMatrix1 = TTKMergeTreeDistanceMatrix(
+    Input=tTKBlockAggregator1, OptionalInput=None
+)
+tTKMergeTreeDistanceMatrix1.Backend = "Branch Mapping Distance (EuroVis 2022)"
+tTKMergeTreeDistanceMatrix1.DistanceSquareRoot = 0
+tTKMergeTreeDistanceMatrix1.Epsilon1 = 0.0
+tTKMergeTreeDistanceMatrix1.Epsilon2 = 100.0
+tTKMergeTreeDistanceMatrix1.Epsilon3 = 100.0
+
+# create a new 'TTK MergeTreeClustering'
+tTKMergeTreeClustering1 = TTKMergeTreeClustering(
+    Input=tTKBlockAggregator1, OptionalInputclustering=None
+)
+tTKMergeTreeClustering1.Backend = "Branch Mapping Distance (EuroVis 2022)"
+tTKMergeTreeClustering1.Deterministic = 1
+tTKMergeTreeClustering1.DimensionSpacing = 0.05
+tTKMergeTreeClustering1.DimensionToshift = "Z"
+tTKMergeTreeClustering1.Epsilon1 = 0.0
+tTKMergeTreeClustering1.Epsilon2 = 100.0
+tTKMergeTreeClustering1.Epsilon3 = 100.0
+tTKMergeTreeClustering1.ImportantPairs = 49.0
+tTKMergeTreeClustering1.ImportantPairsSpacing = 32.0
+tTKMergeTreeClustering1.NonImportantPairsSpacing = 8.0
+
+# save the output
+SaveData("merge_tree_mapping.vtm", proxy=OutputPort(tTKMergeTreeClustering1, 2))
+SaveData("distance_matrix.csv", tTKMergeTreeDistanceMatrix1)

python/mergeTreeBarycenter_pathMapping.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python
+# state file generated using paraview version 5.10.1
+
+#### import the simple module from the paraview
+from paraview.simple import *
+
+# ----------------------------------------------------------------
+# setup the data processing pipelines
+# ----------------------------------------------------------------
+
+# create a new 'XML MultiBlock Data Reader'
+outliervtm = XMLMultiBlockDataReader(FileName=["bdied_outlier/outlier.vtm"])
+
+# create a new 'TTK MergeTree'
+tTKMergeandContourTreeFTM1 = TTKMergeTree(Input=outliervtm)
+tTKMergeandContourTreeFTM1.ScalarField = ["POINTS", "test"]
+tTKMergeandContourTreeFTM1.TreeType = "Split Tree"
+tTKMergeandContourTreeFTM1.UseAllCores = 0
+
+# create a new 'TTK BlockAggregator'
+tTKBlockAggregator1 = TTKBlockAggregator(
+    Input=[
+        tTKMergeandContourTreeFTM1,
+        OutputPort(tTKMergeandContourTreeFTM1, 1),
+        OutputPort(tTKMergeandContourTreeFTM1, 2),
+    ]
+)
+tTKBlockAggregator1.FlattenInput = 0
+
+# create a new 'TTK MergeTreeDistanceMatrix'
+tTKMergeTreeDistanceMatrix1 = TTKMergeTreeDistanceMatrix(
+    Input=tTKBlockAggregator1, OptionalInput=None
+)
+tTKMergeTreeDistanceMatrix1.Backend = "Path Mapping Distance (TopoInVis 2022)"
+tTKMergeTreeDistanceMatrix1.DistanceSquareRoot = 0
+tTKMergeTreeDistanceMatrix1.Epsilon1 = 0.0
+tTKMergeTreeDistanceMatrix1.Epsilon2 = 100.0
+tTKMergeTreeDistanceMatrix1.Epsilon3 = 100.0
+
+# create a new 'TTK MergeTreeClustering'
+tTKMergeTreeClustering1 = TTKMergeTreeClustering(
+    Input=tTKBlockAggregator1, OptionalInputclustering=None
+)
+tTKMergeTreeClustering1.Backend = "Path Mapping Distance (TopoInVis 2022)"
+tTKMergeTreeClustering1.ComputeBarycenter = 1
+tTKMergeTreeClustering1.Deterministic = 1
+tTKMergeTreeClustering1.DimensionSpacing = 0.17
+tTKMergeTreeClustering1.Epsilon1 = 0.0
+tTKMergeTreeClustering1.Epsilon2 = 100.0
+tTKMergeTreeClustering1.Epsilon3 = 100.0
+tTKMergeTreeClustering1.ImportantPairs = 31.0
+tTKMergeTreeClustering1.ImportantPairsSpacing = 32.0
+tTKMergeTreeClustering1.NonImportantPairsSpacing = 8.0
+
+# save the output
+SaveData("merge_tree_barycenter.vtm", proxy=OutputPort(tTKMergeTreeClustering1, 1))
+SaveData("distance_matrix.csv", tTKMergeTreeDistanceMatrix1)