Getting Started with pyEulerCurves
Welcome to pyEulerCurves – a fast and parallel tool for computing Euler Characteristic Curves (ECC) from point clouds and bitmap images.
This guide will help you get started using the library in just a few steps.
Installation
To install the latest version of pyEulerCurves from PyPI:
pip install pyEulerCurves
Or, if you’re developing locally, clone the repository and install in editable mode:
git clone https://github.com/dioscuri-tda/pyEulerCurves.git
cd pyEulerCurves
pip install -e .
Basic Usage
pyEulerCurves can compute Euler characteristic curves from both point cloud data and bitmap images.
Point Cloud Example
import numpy as np
from pyEulerCurves import ECC_from_pointcloud
# Create a simple 2D point cloud
X = np.random.rand(100, 2)
# Initialize ECC transformer
trans = ECC_from_pointcloud(epsilon=0.2)
# Compute ECCs
ecc = trans.fit_transform(X)
# ecc_curve is a list of [filtration, EC] pairs
Bitmap Image Example
import numpy as np
from pyEulerCurves import ECC_from_bitmap
# Create random grayscale image
bitmap = np.random.randint(0, 256, size=(50, 50))
# Initialize ECC transformer for cubical complex
trans = ECC_from_bitmap(periodic_boundary=False)
# Compute ECC
ecc = trans.fit_transform(bitmap)
Visualizing the ECC
You can plot the Euler Characteristic Curve using the helper function:
from pyEulerCurves import plot_euler_curve
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
plot_euler_curve(ecc, this_ax=ax, with_lines=True)
plt.show()
Next Steps
Need help? Feel free to open an issue on the GitHub repository or consult the accompanying paper for theoretical background:
Paweł Dłotko and Davide Gurnari. “Euler characteristic curves and profiles: a stable shape invariant for big data problems.” GigaScience 12 (2023). https://doi.org/10.1093/gigascience/giad094