Metadata-Version: 2.4
Name: iris-iqm
Version: 1.1.0
Summary: ISO/IEC 29794-6 iris image quality metrics
License-Expression: Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: opencv-python-headless>=4.0
Requires-Dist: numba>=0.56
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# iris-iqm

ISO/IEC 29794-6 iris image quality metrics.

A Python library and CLI tool that evaluates iris image quality by computing 29 metrics covering geometric features, image quality, and ISO-standard scores. Ported from MITRE's [BIQT-Iris](https://github.com/mitre/biqt-iris).

## Installation

```bash
pip install .
```

Or in editable mode for development:

```bash
pip install -e ".[dev]"
```

Requires Python 3.8+. Dependencies: `numpy`, `opencv-python-headless`.

## Usage

### Python API

```python
import iris_iqm

# From a file path
result = iris_iqm.evaluate("iris_image.png")

# From a NumPy array
import cv2
img = cv2.imread("iris_image.png", cv2.IMREAD_GRAYSCALE)
result = iris_iqm.evaluate_array(img)

# Access individual metrics
print(result.overall_quality)          # 0-100
print(result.iso_overall_quality)      # 0-100
print(result.features.iris_diameter)   # pixels
print(result.contrast)
print(result.defocus)

# Get all metrics as a dictionary
metrics = result.to_dict()
```

### CLI

```bash
# JSON output (default)
iris-iqm image.png

# CSV output
iris-iqm image.png -o csv

# Table output
iris-iqm image.png -o table

# Multiple images
iris-iqm img1.png img2.png img3.png -o csv
```

## Output Metrics

### Error State

| Metric | Type | Description |
|--------|------|-------------|
| `error_code` | int | Error code (0 = success) |
| `error_message` | str | Error description (empty on success) |

### Geometric Features

| Metric | Type | Description |
|--------|------|-------------|
| `iris_center_x` | int | Iris center X coordinate (pixels) |
| `iris_center_y` | int | Iris center Y coordinate (pixels) |
| `iris_diameter` | int | Iris diameter (pixels) |
| `pupil_center_x` | int | Pupil center X coordinate (pixels) |
| `pupil_center_y` | int | Pupil center Y coordinate (pixels) |
| `pupil_diameter` | int | Pupil diameter (pixels) |
| `image_width` | int | Image width (pixels) |
| `image_height` | int | Image height (pixels) |
| `iris_pupil_ratio` | float | Pupil-to-iris diameter ratio |

### Raw Measurements

| Metric | Type | Description |
|--------|------|-------------|
| `contrast` | int | Image contrast (pixel standard deviation) |
| `defocus` | int | Defocus score (bandpass filter response) |
| `isgs_diff_mean_avg` | float | Mean iris-sclera greyscale difference |
| `ipgs_diff_mean_avg` | float | Mean iris-pupil greyscale difference |
| `usable_iris_area_percent` | float | Percentage of iris area not occluded (0-100) |
| `iris_pupil_gs_diff` | float | Iris-pupil greyscale difference |
| `pupil_circularity_avg_deviation` | float | Average deviation from circular pupil boundary |

### Margin Measurements

| Metric | Type | Description |
|--------|------|-------------|
| `margin_left` | float | Distance from iris to left image border |
| `margin_right` | float | Distance from iris to right image border |
| `margin_top` | float | Distance from iris to top image border |
| `margin_bottom` | float | Distance from iris to bottom image border |

### Normalized Quality Scores (0.0 - 1.0)

| Metric | Description |
|--------|-------------|
| `quality_contrast` | Normalized contrast |
| `quality_defocus` | Normalized defocus |
| `quality_iris_diameter` | Normalized iris diameter (trapezoidal) |
| `quality_isgs` | Normalized iris-sclera greyscale difference |
| `quality_ipgs` | Normalized iris-pupil greyscale difference |
| `quality_ip_ratio` | Normalized iris-pupil ratio |
| `quality_iris_vis` | Normalized usable iris area |
| `quality_margin` | Normalized margin adequacy |

### Overall Quality

| Metric | Type | Description |
|--------|------|-------------|
| `overall_quality` | int | Combined quality score (0-100) |

### ISO/IEC 29794-6 Metrics

| Metric | Type | Description |
|--------|------|-------------|
| `iso_overall_quality` | int | ISO combined quality (0-100) |
| `iso_greyscale_utilization` | float | Shannon entropy of intensity histogram |
| `iso_iris_sclera_contrast` | float | Weber contrast at iris-sclera boundary |
| `iso_iris_pupil_contrast` | float | Weber contrast at iris-pupil boundary |
| `iso_pupil_boundary_circularity` | float | DFT-based circularity of pupil boundary |
| `iso_iris_pupil_concentricity` | float | Normalized iris-pupil center distance |
| `iso_margin_adequacy` | float | Minimum margin from iris to image border |
| `iso_sharpness` | float | Laplacian-based sharpness measure |

## Image Requirements

- Grayscale (color images are converted automatically)
- Minimum size: 256 x 256 pixels
- Maximum size: 1000 x 680 pixels (larger images are downscaled automatically)
- Supported formats: PNG, BMP, JPEG, TIFF, and any format supported by OpenCV

## Testing

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## License

Apache 2.0
