python-ofiq

Python bindings for OFIQ (Open Source Face Image Quality) — the reference implementation for ISO/IEC 29794-5.

Features

• One-time initialization, process many images efficiently
• Unified quality score [0-100] and 25+ individual quality metrics
• Custom exception hierarchy for precise error handling
• Full type hint support

Installation

pip install python-ofiq

Prebuilt wheels are available for:

• Linux x86_64 (manylinux_2_28)
• macOS arm64 (Apple Silicon, macOS 14+)

Download OFIQ models and config (~400 MB):

python-ofiq setup

This stores data in ~/.ofiq/data. Set OFIQ_DATA_DIR to use a custom directory.

Quick Start

import cv2
from ofiq import OFIQ, FaceDetectionError

ofiq = OFIQ()

bgr = cv2.imread("face.png")
rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)

try:
    score = ofiq.scalar_quality(rgb)
    print(f"Quality score: {score}")
except FaceDetectionError:
    print("No face detected")

measures = ofiq.vector_quality(rgb)
print(measures)
# {'UnifiedQualityScore': 85.2, 'Sharpness': 92.1, ...}

measures_with_raw = ofiq.vector_quality(rgb, include_raw=True)
print(measures_with_raw["Sharpness"])
# {'scalar': 92.1, 'raw': 0.847}

Exception Handling

from ofiq import (
    OFIQ,
    OFIQError,
    ConfigError,
    QualityError,
    FaceDetectionError,
    LandmarkError,
    SegmentationError,
)

try:
    score = ofiq.scalar_quality(image)
except FaceDetectionError:
    print("No face in image")
except LandmarkError:
    print("Could not extract facial landmarks")
except QualityError as e:
    print(f"Quality assessment failed: {e}")
except OFIQError as e:
    print(f"OFIQ error: {e}")

Thread Safety

OFIQ instances are not thread-safe. The underlying C++ library uses shared mutable state without synchronization:

• Use one OFIQ instance per thread, or
• Serialize access with a lock, or
• Use multiprocessing instead of threading

Scalar vs Raw Scores

Scalar scores are normalized to [0, 100] where higher is always better. Raw scores are the native OFIQ values before normalization — their range and direction vary per measure. Use include_raw=True when you need the original measurement values.

Available Quality Measures

All measures return scalar values in [0, 100] where higher is better, or None if the measure failed:

API Reference

OFIQ(config_dir="", config_file="ofiq_config.jaxn")

Initialize OFIQ. If config_dir is omitted, uses OFIQ_DATA_DIR env var or ~/.ofiq/data.

scalar_quality(image_rgb) -> float

Compute unified quality score. image_rgb: NumPy uint8 array of shape (H, W, 3) in RGB.

vector_quality(image_rgb, include_raw=False) -> dict

Compute all quality measures. Returns None for failed individual measures.

ofiq.setup(force_download=False) -> str

Download models and config. Returns the data directory path.

ofiq.resolve_data_dir() -> str

Return the resolved data directory.

CLI

python-ofiq setup                    # download models and config
python-ofiq setup --force-download   # re-download even if present
OFIQ_DATA_DIR=/custom/path python-ofiq setup

Version Compatibility

Development

Build from source

Linux (via Docker, produces manylinux wheel):

git clone https://github.com/unicef/python-ofiq.git
cd python-ofiq

docker build -f docker/Dockerfile -t python-ofiq-test .
docker run -it python-ofiq-test python -c "from ofiq import OFIQ; print('OK')"

macOS (Apple Silicon):

brew install cmake git
git clone https://github.com/unicef/python-ofiq.git
cd python-ofiq

bash scripts/build_ofiq.sh
export OFIQ_ROOT="$HOME/OFIQ-Project/install_arm64_mac/Release"
pip install -e .

Or build a wheel directly with cibuildwheel:

pip install cibuildwheel
cibuildwheel --platform macos --output-dir wheelhouse

Run tests

pip install pytest numpy

pytest tests/ -v -m "not integration"

# Integration tests require models
pytest tests/ -v

License

MIT — see LICENSE.

This project wraps the OFIQ C++ library which is also MIT licensed.

Acknowledgments

• BSI for developing OFIQ
• pybind11 for the bindings framework