Metadata-Version: 2.4
Name: hausdorff-stats
Version: 0.1.0
Summary: Multi-stat Hausdorff distance for 3D mesh surfaces (min, max, mean, percentile)
Project-URL: Homepage, https://github.com/rolandshc/hausdorff-stats
Project-URL: Repository, https://github.com/rolandshc/hausdorff-stats
Author: Roland Shum
License-Expression: MIT
License-File: LICENSE
Keywords: 3d,distance,hausdorff,mesh,surface,vtk,vtp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: vtk>=9.0; extra == 'dev'
Provides-Extra: vtk
Requires-Dist: vtk>=9.0; extra == 'vtk'
Description-Content-Type: text/markdown

# hausdorff-stats

Multi-stat bidirectional Hausdorff distance for 3D mesh surfaces.

Returns min, max, mean, and 95th-percentile distances in both directions —
not just the single worst-case number.

## Installation

```bash
pip install hausdorff-stats
```

For point-to-cell distance (projects onto triangle surfaces via VTK):

```bash
pip install hausdorff-stats[vtk]
```

## Quick start

### Point-to-point (numpy arrays)

```python
import numpy as np
from hausdorff_stats import hausdorff_metrics

# Two point clouds of shape (N, 3)
a = np.random.rand(500, 3)
b = np.random.rand(600, 3) + 0.1

result = hausdorff_metrics(a, b)

result.hausdorff      # bidirectional Hausdorff distance
result.mean_a_to_b    # mean distance from A to B
result.p95_b_to_a     # 95th percentile from B to A
result.summary()      # dict of all stats (handy for pandas / JSON)
```

### Point-to-cell (VTP mesh files)

```python
from hausdorff_stats import hausdorff_metrics

result = hausdorff_metrics(
    "surface_a.vtp",
    "surface_b.vtp",
    method="point_to_cell",
)
```

This projects each point onto the nearest triangle cell on the opposite
surface, giving more accurate distances for tessellated geometry.

## Available statistics

`hausdorff_metrics` returns a `HausdorffResult` with:

| Property | Description |
|---|---|
| `hausdorff` | Bidirectional Hausdorff distance (max of both directed maxima) |
| `min_a_to_b` / `min_b_to_a` | Minimum directed distance |
| `max_a_to_b` / `max_b_to_a` | Maximum directed distance |
| `mean_a_to_b` / `mean_b_to_a` | Mean directed distance |
| `p95_a_to_b` / `p95_b_to_a` | 95th percentile directed distance |
| `percentile(q)` | Arbitrary percentile for both directions |
| `summary()` | Flat dict of all stats |

Raw per-point distance arrays are also accessible as `distances_a_to_b` and
`distances_b_to_a`.

## License

MIT
