iris-iqm 1.1.0

ISO/IEC 29794-6 iris image quality metrics

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.

Installation

pip install .

Or in editable mode for development:

pip install -e ".[dev]"

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

Usage

Python API

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

# 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

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

License

Apache 2.0