Metadata-Version: 2.4
Name: fdiss
Version: 0.1.0
Summary: Foveal Disc IoU Scanpath Score - A biologically grounded scanpath similarity metric
Author: Mohammed Amine Kerkouri
License: MIT
Project-URL: Homepage, https://github.com/kmamine/FDISS
Project-URL: Repository, https://github.com/kmamine/FDISS
Project-URL: Issues, https://github.com/kmamine/FDISS/issues
Keywords: eye-tracking,scanpath,similarity,foveal,fixation,iou
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"

# FDISS

**Foveal Disc IoU Scanpath Score**

A biologically grounded scanpath similarity metric that models fixations as foveal discs and computes similarity via bidirectional nearest-neighbour IoU matching.

## Installation

```bash
pip install fdiss
```

## Quick Start

```python
import numpy as np
from fdiss import FDISS

# Initialize the metric
fdiss = FDISS()

# Two scanpaths (x, y coordinates)
S1 = np.array([[100, 200], [150, 250], [300, 150]])
S2 = np.array([[105, 205], [155, 255], [320, 160]])

# Compute foveal radius (45px = 1 degree at 45 px/degree)
r = FDISS.compute_foveal_radius(px_per_degree=45.0, degrees=1.0)

# Evaluate similarity
result = fdiss.evaluate(S1, S2, r)

print(f"FDISS: {result['fdiss']:.4f}")
print(f"Precision: {result['precision']:.4f}")
print(f"Recall: {result['recall']:.4f}")
```

## Features

- **Biologically Grounded**: Models fixations as foveal discs (~1-2° visual angle)
- **Interpretable**: Returns Precision, Recall, and F1 (FDISS) scores
- **Fast**: O(nm) complexity with vectorized NumPy operations
- **No Parameters at Runtime**: Foveal radius computed once from viewing geometry

## Method

FDISS represents each fixation as a foveal disc with radius r, then computes similarity using:

1. **Disc IoU**: Closed-form intersection-over-union of two equal-radius discs
2. **Bidirectional Matching**: Each fixation matched to its best-overlapping counterpart
3. **Precision/Recall**: Coverage from both directions
4. **FDISS**: Harmonic mean of Precision and Recall

## Citation

If you use FDISS in your research, please cite:

```bibtex
@article{kerkouri2026fdiss,
  title={FDISS: Foveal Disc IoU Scanpath Score},
  author={Kerkouri, Mohammed Amine and Tliba, Marouane and Chetouani, Aladine},
  journal={ETRA '26},
  year={2026}
}
```

## License

MIT License
