Matching Distance and Topological Correlation

This repository contains Python code to compute:

• Matching distances between bivariate functions defined on triangulated surfaces.
• Topological correlation between the components of such functions.

References

This code is inspired by the following research articles:

• F. Cagliari, B. Di Fabio, M. Ferri. A new algorithm for computing the 2-dimensional matching distance between size functions, Journal of Mathematical Imaging and Vision, 2013.
• A. Cerri, B. Di Fabio, M. Ferri, P. Frosini. A new approximation algorithm for the matching distance in multidimensional persistence, Journal of Computational Geometry, 2013.

The current implementation is a simplified version and serves as a foundation toward integrating the full algorithms described in the above papers.

Overview

Given two scalar-valued functions f and g on the same triangulated surface, this tool:

1. Constructs persistence diagrams for f, g, and their combinations PHI*_(a,b)=min{a,1-a}max{(f-b)/a,(g+b)/(1-a)}.
2. Computes the bottleneck distances between them.
3. Calculates the matching distances and the topological differences needed for the computation of the topological correlation between f, g.
4. Computes the topological correlation between f, g.

Dependencies

Install all dependencies using:

pip install -r requirements.txt

Repository Structure

topological-matching/
├── matching_distance.py            # Computes matching and bottleneck distances
├── topological_correlation.py     # Computes correlation using the above
├── requirements.txt               # Dependencies
├── README.md                      # This file
├── LICENSE                        # MIT license
├── data/                          # Input OFF files
├── output/                        # Generated output files
├── vertex_components/             # Vertex function values (f and g)
├── vertex_phi_ab/                 # Values of combined functions ϕ*_(a,b)
├── PDs_components/                # Persistence diagrams for f and g
├── PDs_phi_ab/                    # Persistence diagrams for ϕ*_(a,b)

How to Use

1. Put your .off surface models into the data/ directory. Name them as 1.off, 2.off, etc.

for topological correlation: 2. In matching distance.py, choose: - two functions f, g - the parameter n, which will be used to choose 1/(2^n) uniform values in the foliation parameter intervals. 3. Open topological correlation.py. 4. Run:

python topological_correlation.py

5. Follow the terminal instruction. You will have to chose the model on which compute the functions.

This will:

• Call matching_distance.py multiple times with the needed pairs of functions
• Save correlation results to output/correlazioni.txt

The default values are:

• f given by the x component, g given by the y component;
• OFF file already contained in the data/ directory;
• n = 5

for matching distance (if you just need to compute the matching distance between two bivariated functions) 2. In matching distance.py, choose two pairs of functions f_1, g_1 and f_2, g_2. 3. Run:

python matching_distance.py

4. Follow the terminal instruction. You will have to chose the model on which compute the functions.

The default values are:

• f_1 given by the x component, f_2,g_1,g_2 given by the y component;
• OFF file already contained in the data/ directory;
• n = 3

This will:

• compute the bottleneck distances between the components f_1, f_2 and between g_1, g_2
• compute the bottleneck distances between the combined functions PHI_1*_(a,b) and PHI_2*_(a,b)
• compute the matching distance between PHI_1=(f_1, g_1) and PHI_2=(f_2, g_2)

Output

• Distances values:
  • dB_f the bottleneck distances between the first components of the considered functions
  • dB_g the bottleneck distances between the second components of the considered functions
  • dB_ab the bottleneck distances between the combined functions PHI*_(a,b)
  • matching distances
• Correlation values for PHI = (f, g)
• Parameters used: n, C, h, infinito, etc.
• (a,b) that realizes the max dB_ab for each pair

License

This project is licensed under the MIT License © 2025 Isabella Mastroianni.

Author

Isabella Mastroianni - [isabella.mastroianni@ge.imati.cnr.it]