Metadata-Version: 2.4
Name: afis
Version: 1.2.4
Summary: AFIS library: minutiae extraction (classical + LEADER ONNX), matching, and quality
Author-email: Ashok Pant <asokpant@gmail.com>
Maintainer-email: Ashok Pant <asokpant@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ashokpant/afis
Project-URL: Repository, https://github.com/ashokpant/afis
Project-URL: Issues, https://github.com/ashokpant/afis/issues
Keywords: fingerprint,afis,biometrics,minutiae,mindtct,bozorth3,mcc,nfiq,nbis,leader,onnx
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-image>=0.20
Requires-Dist: onnxruntime<1.20,>=1.16; python_version < "3.11"
Requires-Dist: onnxruntime>=1.16; python_version >= "3.11"
Provides-Extra: fast
Requires-Dist: numba>=0.58; extra == "fast"
Provides-Extra: io
Requires-Dist: pillow>=9.0; extra == "io"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pillow>=9.0; extra == "test"
Dynamic: license-file

# afis

AFIS toolkit for fingerprint minutiae extraction, matching, and quality assessment.

## Install

```bash
pip install afis
# or
uv add afis
```

From source (includes the optional native NBIS library):

```bash
make install          # uv sync + make native
```

## Quickstart

```python
from afis import NbisExtractor, MindtctExtractor, SafisExtractor, LeaderExtractor, compute_nfiq2

nbis = NbisExtractor()
a = nbis.extract_minutiae("finger_a.png")
b = nbis.extract_minutiae("finger_b.png")
print(nbis.match(a, b))

# Mix extractor / matcher
proc = NbisExtractor(extractor="gabor", matcher="mcc")
t = proc.extract_minutiae("finger_a.png")

leader = LeaderExtractor()
lt = leader.extract_minutiae("finger_a.png")

q = compute_nfiq2(image)  # NFIQ2-style 0–100
print(q.score)
```

## Extractors

| Name           | Kind                            |
|----------------|---------------------------------|
| `nbis_mindtct` | Native NBIS MINDTCT / LFS V2    |
| `mindtct`      | Pure-Python MINDTCT             |
| `safis`        | SourceAFIS minutiae path        |
| `gabor`        | Gabor enhance + crossing-number |
| `stft`         | STFT enhance + crossing-number  |
| `leader`       | LEADER ONNX                      |

## Matchers

| Name            | Kind                 |
|-----------------|----------------------|
| `nbis_bozorth3` | Native Bozorth3      |
| `bozorth3`      | Pure-Python Bozorth3 |
| `safis`         | SourceAFIS edge crawl|
| `mcc`           | Minutia Cylinder-Code|
| `geometric`     | Rigid geometric      |

## Quality (NFIQ2)

`compute_nfiq2(image)` returns a **0–100** score (ISO/IEC 29794-4 / NFIQ 2 style).

## Benchmark (FVC2004)

FVC B-set protocol on DB1–4_B (10×8 images/DB): genuine = all same-finger impression pairs; impostor = first impressions across fingers. Metrics are macro-averaged over the four DBs.

```bash
uv run python examples/benchmark.py \
  --root /path/to/fingerprint_datasets \
  --workers 10
```

Subset / custom combos:

```bash
uv run python examples/benchmark.py \
  --dbs DB1_B DB3_B --max-fingers 8 --max-imps 4 \
  --extractors nbis_mindtct leader \
  --matchers nbis_bozorth3 mcc geometric \
  --workers 8
```

### Results (FVC2004 DB1–4_B, full)

| Extractor      | Matcher        | EER % | FMR100 % | verify ms | extract ms | match ms |
|----------------|----------------|------:|---------:|----------:|-----------:|---------:|
| leader         | geometric      |  6.78 |    13.48 |    1175.9 |     1167.0 |     8.91 |
| nbis_mindtct   | nbis_bozorth3  | 10.10 |    25.45 |      35.6 |       20.9 |    14.75 |
| leader         | nbis_bozorth3  | 11.82 |    17.59 |    1170.3 |     1167.0 |     3.31 |
| leader         | mcc            | 14.03 |    24.91 |    1169.4 |     1167.0 |     2.41 |
| nbis_mindtct   | mcc            | 15.52 |    26.79 |      25.7 |       20.9 |     4.83 |
| nbis_mindtct   | geometric      | 21.34 |    46.70 |      31.9 |       20.9 |    11.08 |

### Presets

| Preset   | Extractor    | Matcher       | EER % | verify ms |
|----------|--------------|---------------|------:|----------:|
| fast     | nbis_mindtct | mcc           | 15.52 |      25.7 |
| balanced | leader       | nbis_bozorth3 | 11.82 |    1170.3 |
| deep     | leader       | geometric     |  6.78 |    1175.9 |

`verify_ms` ≈ mean extract + mean match (1:1 verify proxy).

## CLI

```bash
afis extract finger.png finger.xyt
afis extract finger.png out.xyt --extractor mindtct
afis extract finger.png out.xyt --extractor leader
afis match a.xyt b.xyt --method bozorth3 --height 480
afis match a.xyt b.xyt --method mcc
afis quality finger.png
```

## Develop

```bash
make install
make test
make build
```

## References

- **NIST NBIS** — MINDTCT / LFS V2 / Bozorth3. [NIST Biometric Image Software](https://www.nist.gov/services-resources/software/nist-biometric-image-software-nbis)
- **NFIQ 2 / ISO/IEC 29794-4** — [usnistgov/NFIQ2](https://github.com/usnistgov/NFIQ2)
- **SourceAFIS** — [algorithm](https://sourceafis.machinezoo.com/algorithm)
- **MCC** — Cappelli, Ferrara & Maltoni (2010). *IEEE TPAMI*. https://doi.org/10.1109/TPAMI.2010.52
- **LEADER** — [pyfing](https://github.com/raffaele-cappelli/pyfing)
- **Gabor enhancement** — Hong, Wan & Jain (1998). *IEEE TPAMI*
- **ISO/IEC 19794-2** — Finger minutiae data interchange
- **FVC / FVC-onGoing** — Verification benchmarks (EER, FMR, FNMR)

## License

MIT. Copyright (c) 2026 Ashok Pant.