ofiqpy
ofiqpy is a Python reimplementation of the fixed, canonical BSI OFIQ v1.1.0
quality-assessment profile. It computes the 27 ISO/IEC 29794-5 components exposed by
OFIQ v1.1.0 plus UnifiedQualityScore using OFIQ's model files.
ofiqpy supports one exact contract:
- OFIQ source tag
v1.1.0, commitbb5dc91d00477e02ce53d2530d28e35021484393. - The canonical
ofiq_config.jaxnwith SHA-256e117286706d799a1e23130db01cfdff7ef36d157b22ecf68dd196052a8a8d0b3. - Twelve exact model artifacts totaling 453,497,937 bytes.
OFIQConfighashes every required artifact before creating inference sessions. - All 28 canonical output components. Arbitrary JAXN measure lists, scalar overrides, and the full C++ API are not implemented.
Confirmed parity evidence
The strict gate runs the live C++ OFIQSampleApp and this package on all 28 real BSI
conformance images. It rejects missing images, duplicate identities, missing components,
non-numeric values, and status mismatches.
At the 0.2.0 source state on 2026-08-16:
| Observation | Result |
|---|---|
| Official C++ conformance suite | 787 / 787 passed |
| Image/component observations | 784 / 784 present |
| Scalar values exactly equal | 784 / 784 |
| Scalar values within tolerance 0 | 784 / 784 |
| Success/FailureToAssess status equal | 784 / 784 |
| Raw values equal at six-decimal CSV precision | 698 to 702 / 784 across verified Linux runs |
| Raw values within the named component policy | 784 / 784 |
Raw values determine the verdict under the immutable
bsi-ofiq-v1.1.0-cpu-raw-csv-v1 component policy. The policy compares the six-decimal
values emitted by OFIQSampleApp; ten deterministic components require equality and each
remaining component has a unit-specific bound and rationale. Raw values are excluded only
when either implementation reports FailureToAssess, where OFIQ does not define a raw
result. The diagnostic exact count was 698 on the GitHub Python 3.11.15 runner and 702 on
the local Python 3.11.14 verification host. This environment-sensitive count is reported,
but it does not determine conformance. The earlier unbound 1,197-image and universal
bit-exactness claims are not used as release evidence.
A separate, non-redistributed diagnostic reran the recovered 1,197-image CelebA selection with aggregate provenance. All 33,516 statuses matched; 33,483 scalars were exact and all were within one point; all 33,430 defined raw comparisons met the component policy. This binds the currently available bytes but does not retroactively prove that the original unhashed run used identical bytes. See Conformance.
Install and configure
Use Python 3.11 or 3.12 on Linux x86-64, including Linux inside Windows WSL2. The canonical runtime is CPU-only and uses the pinned NumPy, OpenCV, and ONNX Runtime dependencies. Do not install it into the OpenFIQA/QualSight application environment or replace its backend with a GPU build while claiming the canonical profile's conformance.
python3.11 -m venv .venv-ofiqpy
source .venv-ofiqpy/bin/activate
python -m pip install ofiqpy
Version 0.2.2 updates packaging and removes host-specific raw-diagnostic assertions. Runtime dependencies, canonical model hashes, scientific producers, and the named raw tolerance policy are unchanged. Publication remains gated by the complete real-data CI workflow.
For an already authorized local profile, no native compilation or automatic download is needed:
export OFIQPY_OFIQ_DATA="$AUTHORIZED_OFIQ_DATA"
python -m ofiqpy.config
The directory must contain the canonical ofiq_config.jaxn and exact
models/ tree. Configuration loading verifies all twelve required model
artifacts before inference. It does not import images, copy the profile, or
grant redistribution rights.
To acquire the upstream profile explicitly, review the upstream model terms
first. The model archive URL and extraction layout below are those used by
OFIQ v1.1.0's build.
This model-only route uses git, curl, and unzip, not a C++ toolchain:
git clone --branch v1.1.0 https://github.com/BSI-OFIQ/OFIQ-Project.git ../OFIQ-Project
curl --fail --location --output OFIQ-MODELS.zip \
https://standards.iso.org/iso-iec/29794/-5/ed-1/en/OFIQ-MODELS.zip
unzip -n OFIQ-MODELS.zip -d ../OFIQ-Project/data
export OFIQPY_OFIQ_ROOT="$(cd ../OFIQ-Project && pwd)"
export OFIQPY_OFIQ_DATA="$OFIQPY_OFIQ_ROOT/data"
python -m ofiqpy.config
The verifier rejects any changed or missing canonical bytes, including a
future upstream archive that no longer matches this package. -n avoids
overwriting an existing model tree; use a separate destination rather than
altering a previously bound profile. ofiqpy does not bundle or redistribute
the archive, models, or BSI images.
The examples below use BSI conformance captures, obtained separately under their terms. To run those examples without building native OFIQ:
curl --fail --location --output OFIQ-IMAGES.zip \
https://standards.iso.org/iso-iec/29794/-5/ed-1/en/OFIQ-IMAGES.zip
unzip -n OFIQ-IMAGES.zip -d "$OFIQPY_OFIQ_DATA/tests"
Only the strict live-C++ conformance gate needs the native reference build:
(cd "$OFIQPY_OFIQ_ROOT/scripts" && sh build.sh)
Native build prerequisites and licenses remain governed by upstream OFIQ. Neither model-only configuration verification nor package installation is a new conformance result.
Python API
Use Assessor when status and failure information matters:
import os
from pathlib import Path
from ofiqpy import Assessor
from ofiqpy.config import OFIQConfig
data_root = Path(os.environ["OFIQPY_OFIQ_DATA"])
assessor = Assessor(OFIQConfig(data_root=data_root))
result = assessor.assess(data_root / "tests" / "images" / "r-01-frontal.png")
print(result.status)
print(result.components["UnifiedQualityScore"])
Assessor loads and validates the complete model graph before assessment and serializes
access to mutable OpenCV/ONNX sessions. A component exception produces a typed
FailureToAssess only for that component or compound component group; unaffected results
are retained.
The original mapping API remains as a compatibility adapter:
import os
from pathlib import Path
from ofiqpy import assess
image = Path(os.environ["OFIQPY_OFIQ_DATA"]) / "tests" / "images" / "r-01-frontal.png"
scores = assess(image)
print(scores["UnifiedQualityScore"])
It returns {component: (raw, scalar)} and returns an empty mapping only when no face is
detected. Unreadable paths, invalid arrays, and preprocessing failures raise instead of
being collapsed into a no-face result. New integrations should use Assessor.assess or
assess_typed when the typed failure detail is required.
CLI and batch
ofiqpy \
-i "$OFIQPY_OFIQ_DATA/tests/images/r-01-frontal.png" \
-o assessment.csv
python -m ofiqpy.batch \
-i "$OFIQPY_OFIQ_DATA/tests/images" \
-o assessments.csv \
--resume
The semicolon CSV uses the canonical 28-component OFIQ column order and preserves the
full supplied/discovered image path. CSV quoting protects delimiters in paths. Resume
validates the exact header and row width and uses the full path identity, so recursive
duplicate basenames do not collide. Batch execution defaults to one worker because each
worker owns a complete model graph; additional workers require an explicit -w value and
start with Python's clean spawn process context. An unreadable image or preprocessing
failure exits nonzero rather than silently writing a whole-image sentinel row.
On the tested 64-image real-data workload, version 0.2.0 processed 2.649 images/s at one worker, 2.391 at two, and 2.140 at four; median process-tree RSS rose from 1.292 GiB to 2.450 and 4.723 GiB. One worker is therefore the measured default for that host, not a universal optimum. See Runtime performance.
Reproduce the strict gate
python -m ofiqpy.conformance \
--ofiq-root "$OFIQPY_OFIQ_ROOT" \
--images "$OFIQPY_OFIQ_DATA/tests/images" \
--expected-count 28 \
--scalar-tolerance 0 \
--source-root "$PWD" \
--report conformance-report.json
The command exits nonzero for any conformance failure or incomplete comparison. The JSON report binds the source tree, OFIQ and ofiqpy commits, official binary and library hashes, canonical config/model hashes, and the complete input set.
License and attribution
ofiqpy is MIT-licensed. OFIQ is developed by the German Federal Office for Information
Security (BSI) and is also MIT-licensed. OFIQ's models have their own license terms; review
the license files downloaded into the OFIQ data directory before redistribution.
This project is independent and is not endorsed by ISO, IEC, or BSI.
Metadata
Release files for ofiqpy 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ofiqpy-0.2.2.tar.gz | 234.9 kB | With provenance | Details for ofiqpy-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ofiqpy-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for ofiqpy-0.2.2-py3-none-any.whl |
Total release size: 286.1 kB
Release files / ofiqpy-0.2.2.tar.gz
| Download URL | ofiqpy-0.2.2.tar.gz |
|---|---|
| Size | 234.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
98ed31e328cac1b3de7748c1267e50c0920b9f918563c5bb6f5fda341b4c883b
|
|
BLAKE2b-256 checksum How to use checksums |
3a018982c6fda0a29f5dce88d8e9601b6ddaf0443b828aafe69abd7c42b12229
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.
Transparency logRelease files / ofiqpy-0.2.2-py3-none-any.whl
| Download URL | ofiqpy-0.2.2-py3-none-any.whl |
|---|---|
| Size | 51.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e88ac05491e8ed8eaa9e176bd28352f12327cda150356bb4bf6334dda941e18c
|
|
BLAKE2b-256 checksum How to use checksums |
1c7199627b07182219b9f05f723ffaf937f969d8a6ad81cb5e0f1bf995a6bed2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.
Transparency logSecurity for ofiqpy 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ofiqpy-0.2.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.