ofiqpy 0.1.0__tar.gz

ofiqpy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Storey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ofiqpy-0.1.0/NOTICE

@@ -0,0 +1,27 @@
+ofiqpy — a faithful Python port of OFIQ v1.1.0
+==============================================
+
+ofiqpy reproduces the algorithms of OFIQ (Open Source Face Image Quality), the
+ISO/IEC 29794-5 reference implementation developed by the German Federal Office
+for Information Security (BSI), Copyright (c) 2024, MIT-licensed:
+
+    https://github.com/BSI-OFIQ/OFIQ-Project
+
+Models are NOT bundled
+----------------------
+ofiqpy loads OFIQ's own model files at runtime (SSD face detector, ADNet-98
+landmarks, 3DDFA-V2 pose, BiSeNet face parsing, face-occlusion segmentation,
+sharpness random forest, compression CNN, HSEmotion + AdaBoost expression, and
+the MagFace unified-quality model). These files ship with OFIQ and may be
+licensed separately from the OFIQ source (see OFIQ's LICENSE.md). They are NOT
+redistributed with ofiqpy.
+
+To run ofiqpy, obtain the models from an OFIQ install and set:
+
+    export OFIQPY_OFIQ_DATA=/path/to/OFIQ-Project/data
+
+Conformance
+-----------
+ofiqpy targets agreement with the OFIQ reference to within +/- 1 quality point
+per component (the ISO/IEC 29794-5 Annex A criterion). See the docs for the
+validated conformance figures.

ofiqpy-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: ofiqpy
+Version: 0.1.0
+Summary: A faithful Python port of OFIQ v1.1.0 (ISO/IEC 29794-5 face image quality), matching the reference within ±1.
+Author: Aaron Storey
+License: MIT
+Project-URL: Homepage, https://github.com/AVHBAC/ofiqpy
+Project-URL: Documentation, https://avhbac.github.io/ofiqpy/
+Project-URL: Repository, https://github.com/AVHBAC/ofiqpy
+Project-URL: Issues, https://github.com/AVHBAC/ofiqpy/issues
+Keywords: face,image quality,biometrics,ISO 29794-5,OFIQ,FIQA
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy<2,>=1.23
+Requires-Dist: opencv-python-headless==4.5.5.64
+Requires-Dist: onnxruntime==1.18.1
+Provides-Extra: verify
+Requires-Dist: pandas>=1.5; extra == "verify"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: pandas>=1.5; extra == "dev"
+Requires-Dist: jupyter>=1.0; extra == "dev"
+Dynamic: license-file
+
+# ofiqpy — a faithful Python port of OFIQ v1.1.0
+
+[![CI & Release](https://github.com/AVHBAC/ofiqpy/actions/workflows/workflow.yml/badge.svg)](https://github.com/AVHBAC/ofiqpy/actions/workflows/workflow.yml)
+[![Docs](https://github.com/AVHBAC/ofiqpy/actions/workflows/docs.yml/badge.svg)](https://avhbac.github.io/ofiqpy/)
+[![PyPI](https://img.shields.io/pypi/v/ofiqpy.svg)](https://pypi.org/project/ofiqpy/)
+[![Python](https://img.shields.io/pypi/pyversions/ofiqpy.svg)](https://pypi.org/project/ofiqpy/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A behavior-preserving Python reimplementation of the BSI **OFIQ** ISO/IEC 29794-5
+face image quality library. `ofiqpy` **reuses OFIQ's own model files and reproduces
+its exact `.cpp` algorithms**, matching the live OFIQ reference to within **±1** per
+component (the ISO/IEC 29794-5 Annex A.2 conformance criterion).
+
+📖 **Docs: <https://avhbac.github.io/ofiqpy/>**
+
+> Status: **full coverage + near-exact parity.** All 27 ISO components + UnifiedQualityScore,
+> an OFIQ-compatible CSV writer, a CLI, and a parallel batch runner — all gated against
+> live `OFIQSampleApp`. Validated on **1,000+ real CelebA images**: 27/28 components fully
+> conformant (±1 on every image, most bit-exact); ~99.99% of all component-image pairs
+> within ±1. The rare per-image residuals are numerical boundaries of discrete/learned
+> models (RTrees vote, AdaBoost score, round tie), not algorithm gaps.
+
+## Install & run
+
+```bash
+pip install ofiqpy
+export OFIQPY_OFIQ_DATA=/path/to/OFIQ-Project/data   # OFIQ's models (not bundled)
+
+ofiqpy -i face.jpg -o out.csv                        # CLI
+```
+```python
+from ofiqpy import assess
+scores = assess("face.jpg")            # {component: (raw, scalar)}
+print(scores["UnifiedQualityScore"])   # (magnitude, 0-100)
+```
+
+See [Installation](https://avhbac.github.io/ofiqpy/installation/) and
+[Quickstart](https://avhbac.github.io/ofiqpy/quickstart/).
+
+## Design
+
+- **Same weights.** Models are loaded directly from the reference checkout
+  `OFIQ-Project/data/models/` via `config.py` (SSD caffemodel, ADNet-98 ONNX,
+  3DDFA-V2 ONNX, BiSeNet parsing ONNX, occlusion-seg ONNX, ssim-248 ONNX, MagFace ONNX).
+  No re-training, no substitute backbones.
+- **Same math.** Detection, ADNet landmark crop/denorm, the 5-point LMEDS similarity
+  alignment to 616×616, the landmarked-region mask, `tmetric`, the generic
+  `h·(a+s·sigmoid(x;x0,w))` scalar mapping, and each measure are ported line-faithfully
+  from OFIQ's C++ (see per-module docstrings for `file:line` provenance).
+- **Same versions.** The isolated `.venv` pins **OpenCV 4.5.5** and **onnxruntime 1.18.1**
+  to match OFIQ's build (`libofiq_lib.so` links OpenCV 4.5.5; bundles onnxruntime 1.18.1).
+- **Gated, not asserted.** `tests/verify_ofiq.py` runs live OFIQ and checks
+  `|port_scalar − ofiq_scalar| ≤ 1` per image; `tests/gate_slice.py` reports it.
+
+## Conformance (1,000+ real CelebA images, port vs live OFIQ, ISO Annex A ±1)
+
+Validated on **1,197 real CelebA images**: **27 of 28 components fully conformant** (±1 on
+every image), 24 of them **bit-exact** (maxΔ=0). **~99.99% of all component-image pairs are
+within ISO ±1** (mean |Δ| ≤ 0.02 for every component).
+
+The rare per-image residuals:
+- **Sharpness — 1 image at Δ=2**: OFIQ's RTrees vote count differs by exactly 2 trees at a
+  split-threshold knife-edge (a sub-LSB feature difference flips 2 borderline votes through
+  the step-function forest). Bit-exact on the rest.
+- **BackgroundUniformity / ExpressionNeutrality / NoHeadCoverings — one ±1 image each**, a
+  single sigmoid/round boundary.
+
+Sharpness (RTrees) and ExpressionNeutrality (dual EfficientNet + AdaBoost) run OFIQ's own
+`cv2.ml` / ONNX models; UnifiedQualityScore runs OFIQ's MagFace ONNX. These four residuals
+are numerical boundaries of discrete/learned models, not algorithm gaps.
+
+### How parity was reached (the residual was a bug, not a build limit)
+
+An earlier version of this port was only ~96% conformant, and the residual was *wrongly*
+attributed to a build-level OpenCV float difference. To test that, ctypes bridges were
+built against OFIQ's own conan OpenCV static libs (`native/ofiq_cv.cpp`, `ofiq_ssd.cpp`)
+and used to compare OFIQ's compiled `estimateAffinePartial2D`, `warpAffine`, `resize`, and
+the SSD dnn forward pass against the pip `opencv-python` wheel. **Every OpenCV operation
+was bit-identical** — which disproved the build-level theory and localized the divergence
+to the **ADNet landmark back-projection**: OFIQ scales landmarks back with
+`squareBox.height / 256` (`adnet_landmarks.cpp:313`), but `makeSquareBoundingBox`'s
+`floor`/`ceil` can leave the box 1px non-square, and the port had used the *width*. On
+exactly-square detector boxes it matched; otherwise it drifted ~1px, propagating (via the
+alignment source points → affine → whole aligned face) into every landmark-sensitive
+measure. One-character fix (width→height); all 27 non-model components went bit-exact.
+
+The bridges in `native/` are diagnostic only — the runtime uses pip `cv2`, which is
+bit-identical to OFIQ's OpenCV. No source build of OpenCV was needed.
+
+## Layout
+
+```
+ofiqpy/
+  config.py            JAXN loader + OFIQ model resolver + sigmoid params
+  sigmoid.py           OFIQ ScalarConversion (Measure.h:271-285)
+  session.py           shared preprocessing products
+  pipeline.py          detect -> pose -> landmarks -> align -> parse -> occlusion -> region
+  detectors/ssd.py     SSD (OpenCV DNN, Caffe)
+  landmarks/adnet.py   ADNet-98 + square-crop helpers
+  align.py             616x616 alignment, landmarked region (GetFaceMask), tmetric, luminance
+  pose/tddfa.py        3DDFA-V2 pose
+  segmentation/        BiSeNet parsing, face-occlusion seg
+  measures/
+    core.py            model cache + dispatch; C03/C09/C17/C20, unified, HeadPose (slot swap)
+    geometry.py        C11,C12,C13,C19,C24-C27
+    pixel.py           C01,C02,C04(var),C05,C06,C07,C10
+    models.py          C08 Sharpness (RTrees), C14/C15/C16 occlusion, C18 Expression
+    helpers.py         get_distance/get_middle, c_round, landmark index maps
+  output.py            OFIQ-format CSV (named cols, raw + .scalar)
+  cli.py               OFIQSampleApp-compatible CLI
+tests/
+  verify_ofiq.py       runs live OFIQ, ±1 gate
+  gate_slice.py        full-coverage conformance runner
+```
+
+## Run
+
+```bash
+export OFIQPY_OFIQ_DATA=/path/to/OFIQ-Project/data
+
+ofiqpy -i <image|dir> -o out.csv               # single / small runs (OFIQ-format CSV)
+python -m ofiqpy.batch -i <dir> -o out.csv -w 8 --resume   # parallel batch
+
+# reproduce the conformance gate (needs a built OFIQSampleApp)
+export OFIQPY_OFIQ_ROOT=/path/to/OFIQ-Project
+export OFIQPY_TEST_IMAGES=/path/to/images
+python tests/gate_slice.py 1000
+```
+
+Full documentation: <https://avhbac.github.io/ofiqpy/>.
+
+## License & attribution
+
+`ofiqpy` is released under the [MIT License](LICENSE).
+
+It is a faithful port of **OFIQ** (Open Source Face Image Quality), developed by the German
+Federal Office for Information Security (BSI), Copyright © 2024, MIT-licensed
+(<https://github.com/BSI-OFIQ/OFIQ-Project>). Please acknowledge OFIQ when using ofiqpy.
+
+**Models are not bundled.** ofiqpy loads OFIQ's own model files at runtime; they ship with
+OFIQ and may be licensed separately (see OFIQ's `LICENSE.md`). Obtain them from an OFIQ
+install and set `OFIQPY_OFIQ_DATA`. See [`NOTICE`](NOTICE) and the
+[licensing docs](https://avhbac.github.io/ofiqpy/licensing/).

ofiqpy-0.1.0/README.md

@@ -0,0 +1,143 @@
+# ofiqpy — a faithful Python port of OFIQ v1.1.0
+
+[![CI & Release](https://github.com/AVHBAC/ofiqpy/actions/workflows/workflow.yml/badge.svg)](https://github.com/AVHBAC/ofiqpy/actions/workflows/workflow.yml)
+[![Docs](https://github.com/AVHBAC/ofiqpy/actions/workflows/docs.yml/badge.svg)](https://avhbac.github.io/ofiqpy/)
+[![PyPI](https://img.shields.io/pypi/v/ofiqpy.svg)](https://pypi.org/project/ofiqpy/)
+[![Python](https://img.shields.io/pypi/pyversions/ofiqpy.svg)](https://pypi.org/project/ofiqpy/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A behavior-preserving Python reimplementation of the BSI **OFIQ** ISO/IEC 29794-5
+face image quality library. `ofiqpy` **reuses OFIQ's own model files and reproduces
+its exact `.cpp` algorithms**, matching the live OFIQ reference to within **±1** per
+component (the ISO/IEC 29794-5 Annex A.2 conformance criterion).
+
+📖 **Docs: <https://avhbac.github.io/ofiqpy/>**
+
+> Status: **full coverage + near-exact parity.** All 27 ISO components + UnifiedQualityScore,
+> an OFIQ-compatible CSV writer, a CLI, and a parallel batch runner — all gated against
+> live `OFIQSampleApp`. Validated on **1,000+ real CelebA images**: 27/28 components fully
+> conformant (±1 on every image, most bit-exact); ~99.99% of all component-image pairs
+> within ±1. The rare per-image residuals are numerical boundaries of discrete/learned
+> models (RTrees vote, AdaBoost score, round tie), not algorithm gaps.
+
+## Install & run
+
+```bash
+pip install ofiqpy
+export OFIQPY_OFIQ_DATA=/path/to/OFIQ-Project/data   # OFIQ's models (not bundled)
+
+ofiqpy -i face.jpg -o out.csv                        # CLI
+```
+```python
+from ofiqpy import assess
+scores = assess("face.jpg")            # {component: (raw, scalar)}
+print(scores["UnifiedQualityScore"])   # (magnitude, 0-100)
+```
+
+See [Installation](https://avhbac.github.io/ofiqpy/installation/) and
+[Quickstart](https://avhbac.github.io/ofiqpy/quickstart/).
+
+## Design
+
+- **Same weights.** Models are loaded directly from the reference checkout
+  `OFIQ-Project/data/models/` via `config.py` (SSD caffemodel, ADNet-98 ONNX,
+  3DDFA-V2 ONNX, BiSeNet parsing ONNX, occlusion-seg ONNX, ssim-248 ONNX, MagFace ONNX).
+  No re-training, no substitute backbones.
+- **Same math.** Detection, ADNet landmark crop/denorm, the 5-point LMEDS similarity
+  alignment to 616×616, the landmarked-region mask, `tmetric`, the generic
+  `h·(a+s·sigmoid(x;x0,w))` scalar mapping, and each measure are ported line-faithfully
+  from OFIQ's C++ (see per-module docstrings for `file:line` provenance).
+- **Same versions.** The isolated `.venv` pins **OpenCV 4.5.5** and **onnxruntime 1.18.1**
+  to match OFIQ's build (`libofiq_lib.so` links OpenCV 4.5.5; bundles onnxruntime 1.18.1).
+- **Gated, not asserted.** `tests/verify_ofiq.py` runs live OFIQ and checks
+  `|port_scalar − ofiq_scalar| ≤ 1` per image; `tests/gate_slice.py` reports it.
+
+## Conformance (1,000+ real CelebA images, port vs live OFIQ, ISO Annex A ±1)
+
+Validated on **1,197 real CelebA images**: **27 of 28 components fully conformant** (±1 on
+every image), 24 of them **bit-exact** (maxΔ=0). **~99.99% of all component-image pairs are
+within ISO ±1** (mean |Δ| ≤ 0.02 for every component).
+
+The rare per-image residuals:
+- **Sharpness — 1 image at Δ=2**: OFIQ's RTrees vote count differs by exactly 2 trees at a
+  split-threshold knife-edge (a sub-LSB feature difference flips 2 borderline votes through
+  the step-function forest). Bit-exact on the rest.
+- **BackgroundUniformity / ExpressionNeutrality / NoHeadCoverings — one ±1 image each**, a
+  single sigmoid/round boundary.
+
+Sharpness (RTrees) and ExpressionNeutrality (dual EfficientNet + AdaBoost) run OFIQ's own
+`cv2.ml` / ONNX models; UnifiedQualityScore runs OFIQ's MagFace ONNX. These four residuals
+are numerical boundaries of discrete/learned models, not algorithm gaps.
+
+### How parity was reached (the residual was a bug, not a build limit)
+
+An earlier version of this port was only ~96% conformant, and the residual was *wrongly*
+attributed to a build-level OpenCV float difference. To test that, ctypes bridges were
+built against OFIQ's own conan OpenCV static libs (`native/ofiq_cv.cpp`, `ofiq_ssd.cpp`)
+and used to compare OFIQ's compiled `estimateAffinePartial2D`, `warpAffine`, `resize`, and
+the SSD dnn forward pass against the pip `opencv-python` wheel. **Every OpenCV operation
+was bit-identical** — which disproved the build-level theory and localized the divergence
+to the **ADNet landmark back-projection**: OFIQ scales landmarks back with
+`squareBox.height / 256` (`adnet_landmarks.cpp:313`), but `makeSquareBoundingBox`'s
+`floor`/`ceil` can leave the box 1px non-square, and the port had used the *width*. On
+exactly-square detector boxes it matched; otherwise it drifted ~1px, propagating (via the
+alignment source points → affine → whole aligned face) into every landmark-sensitive
+measure. One-character fix (width→height); all 27 non-model components went bit-exact.
+
+The bridges in `native/` are diagnostic only — the runtime uses pip `cv2`, which is
+bit-identical to OFIQ's OpenCV. No source build of OpenCV was needed.
+
+## Layout
+
+```
+ofiqpy/
+  config.py            JAXN loader + OFIQ model resolver + sigmoid params
+  sigmoid.py           OFIQ ScalarConversion (Measure.h:271-285)
+  session.py           shared preprocessing products
+  pipeline.py          detect -> pose -> landmarks -> align -> parse -> occlusion -> region
+  detectors/ssd.py     SSD (OpenCV DNN, Caffe)
+  landmarks/adnet.py   ADNet-98 + square-crop helpers
+  align.py             616x616 alignment, landmarked region (GetFaceMask), tmetric, luminance
+  pose/tddfa.py        3DDFA-V2 pose
+  segmentation/        BiSeNet parsing, face-occlusion seg
+  measures/
+    core.py            model cache + dispatch; C03/C09/C17/C20, unified, HeadPose (slot swap)
+    geometry.py        C11,C12,C13,C19,C24-C27
+    pixel.py           C01,C02,C04(var),C05,C06,C07,C10
+    models.py          C08 Sharpness (RTrees), C14/C15/C16 occlusion, C18 Expression
+    helpers.py         get_distance/get_middle, c_round, landmark index maps
+  output.py            OFIQ-format CSV (named cols, raw + .scalar)
+  cli.py               OFIQSampleApp-compatible CLI
+tests/
+  verify_ofiq.py       runs live OFIQ, ±1 gate
+  gate_slice.py        full-coverage conformance runner
+```
+
+## Run
+
+```bash
+export OFIQPY_OFIQ_DATA=/path/to/OFIQ-Project/data
+
+ofiqpy -i <image|dir> -o out.csv               # single / small runs (OFIQ-format CSV)
+python -m ofiqpy.batch -i <dir> -o out.csv -w 8 --resume   # parallel batch
+
+# reproduce the conformance gate (needs a built OFIQSampleApp)
+export OFIQPY_OFIQ_ROOT=/path/to/OFIQ-Project
+export OFIQPY_TEST_IMAGES=/path/to/images
+python tests/gate_slice.py 1000
+```
+
+Full documentation: <https://avhbac.github.io/ofiqpy/>.
+
+## License & attribution
+
+`ofiqpy` is released under the [MIT License](LICENSE).
+
+It is a faithful port of **OFIQ** (Open Source Face Image Quality), developed by the German
+Federal Office for Information Security (BSI), Copyright © 2024, MIT-licensed
+(<https://github.com/BSI-OFIQ/OFIQ-Project>). Please acknowledge OFIQ when using ofiqpy.
+
+**Models are not bundled.** ofiqpy loads OFIQ's own model files at runtime; they ship with
+OFIQ and may be licensed separately (see OFIQ's `LICENSE.md`). Obtain them from an OFIQ
+install and set `OFIQPY_OFIQ_DATA`. See [`NOTICE`](NOTICE) and the
+[licensing docs](https://avhbac.github.io/ofiqpy/licensing/).

ofiqpy-0.1.0/ofiqpy/__init__.py

@@ -0,0 +1,61 @@
+"""ofiqpy — a faithful Python port of OFIQ v1.1.0 (ISO/IEC 29794-5 face image quality).
+
+Reuses OFIQ's own models and reproduces its exact algorithms, matching the reference
+within +/- 1 quality point per component. Point ofiqpy at an OFIQ install's data/ dir:
+
+    export OFIQPY_OFIQ_DATA=/path/to/OFIQ-Project/data
+
+Then:
+
+    from ofiqpy import assess
+    scores = assess("face.jpg")   # {component_name: (raw, scalar)}
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+_PIPE = None
+_MEAS = None
+
+
+def _lazy():
+    """Build (once) the shared pipeline + measures. Models load on first use."""
+    global _PIPE, _MEAS
+    if _PIPE is None:
+        from .config import OFIQConfig
+        from .measures.core import Measures
+        from .pipeline import OFIQPipeline
+        cfg = OFIQConfig()
+        _PIPE = OFIQPipeline(cfg)
+        _MEAS = Measures(cfg)
+    return _PIPE, _MEAS
+
+
+def assess(image: "str | object") -> dict:
+    """Assess one image and return ``{component_name: (raw, scalar)}``.
+
+    Args:
+        image: path to an image file (str or PathLike), or a BGR uint8 numpy
+            array of shape (H, W, 3).
+
+    Returns:
+        Mapping of OFIQ component name to ``(raw native value, 0-100 scalar)``. Empty
+        if no face is detected.
+    """
+    import numpy as np
+
+    pipe, meas = _lazy()
+    if isinstance(image, np.ndarray):
+        bgr = image
+    else:
+        import cv2
+        bgr = cv2.imread(str(image))
+        if bgr is None:
+            raise FileNotFoundError(f"could not read image: {image}")
+    session = pipe.process(bgr)
+    if session.bbox is None:
+        return {}
+    return meas.compute(session)
+
+
+__all__ = ["assess", "__version__"]

ofiqpy-0.1.0/ofiqpy/align.py

@@ -0,0 +1,109 @@
+"""Alignment (616x616), landmarked-region mask, tmetric, luminance.
+
+Faithful port of utils.cpp:236-331, FaceMeasures.cpp:98-228, image_utils.cpp:43-112.
+"""
+from __future__ import annotations
+
+import math
+
+import cv2
+import numpy as np
+
+# ADNet FaceMap indices (adnet_FaceMap.h)
+LEFT_EYE_CORNERS = (60, 64)
+RIGHT_EYE_CORNERS = (68, 72)
+NOSE = 54
+RIGHT_MOUTH = 76
+LEFT_MOUTH = 82
+CHIN = 16
+
+REF_POINTS = np.float32([
+    [251, 272], [364, 272], [308, 336], [262, 402], [355, 402],
+])
+
+
+def _round(x):
+    return math.copysign(math.floor(abs(x) + 0.5), x)
+
+
+def eye_centers(P: np.ndarray):
+    """Midpoints of eye-corner pairs, each coord rounded (utils.cpp:302-317)."""
+    l = (_round(P[LEFT_EYE_CORNERS[0], 0] + 0.5 * (P[LEFT_EYE_CORNERS[1], 0] - P[LEFT_EYE_CORNERS[0], 0])),
+         _round(P[LEFT_EYE_CORNERS[0], 1] + 0.5 * (P[LEFT_EYE_CORNERS[1], 1] - P[LEFT_EYE_CORNERS[0], 1])))
+    r = (_round(P[RIGHT_EYE_CORNERS[0], 0] + 0.5 * (P[RIGHT_EYE_CORNERS[1], 0] - P[RIGHT_EYE_CORNERS[0], 0])),
+         _round(P[RIGHT_EYE_CORNERS[0], 1] + 0.5 * (P[RIGHT_EYE_CORNERS[1], 1] - P[RIGHT_EYE_CORNERS[0], 1])))
+    return l, r
+
+
+def align(img: np.ndarray, P: np.ndarray):
+    """Return (aligned 616x616 BGR, aligned_landmarks (98,2), affine 2x3)."""
+    Lc, Rc = eye_centers(P)
+    src = np.float32([
+        [Lc[0], Lc[1]], [Rc[0], Rc[1]],
+        [P[NOSE, 0], P[NOSE, 1]],
+        [P[RIGHT_MOUTH, 0], P[RIGHT_MOUTH, 1]],
+        [P[LEFT_MOUTH, 0], P[LEFT_MOUTH, 1]],
+    ])
+    M, _ = cv2.estimateAffinePartial2D(src, REF_POINTS, method=cv2.LMEDS)
+    aligned = cv2.warpAffine(img, M, (616, 616))  # default INTER_LINEAR, BORDER_CONSTANT 0
+    ap = cv2.transform(P.reshape(-1, 1, 2).astype(np.float32), M).reshape(-1, 2)
+    aligned_lms = np.array([[_round(x), _round(y)] for x, y in ap], np.float64)
+    return aligned, aligned_lms, M
+
+
+def tmetric(P: np.ndarray) -> float:
+    """||chin - eye_midpoint|| (utils.cpp:319-331). Space-agnostic; pass the right landmarks."""
+    Lc, Rc = eye_centers(P)
+    eye_mid = ((Lc[0] + Rc[0]) / 2.0, (Lc[1] + Rc[1]) / 2.0)
+    chin = P[CHIN]
+    return float(math.hypot(chin[0] - eye_mid[0], chin[1] - eye_mid[1]))
+
+
+def landmarked_region(aligned_lms: np.ndarray, height=616, width=616, alpha=0.0) -> np.ndarray:
+    """GetFaceMask at alpha=0 (FaceMeasures.cpp:173-226): convex hull -> 224 -> resize."""
+    pts = aligned_lms.astype(np.int32)
+    hull = cv2.convexHull(pts)
+    rx, ry, rw, rh = cv2.boundingRect(hull)
+    b = int(ry - rh * 0.05)
+    d = int(ry + rh * 1.05)
+    a = int(rx + rw / 2.0 - (d - b) / 2.0)
+    c = int(rx + rw / 2.0 + (d - b) / 2.0)
+    S = 224
+    hull_s = ((hull.reshape(-1, 2).astype(np.float64) - (a, b)) / (d - b) * S).astype(np.int32)
+    mask = np.zeros((S, S), np.uint8)
+    cv2.fillConvexPoly(mask, hull_s, 1)
+    mrs = cv2.resize(mask, (c - a, d - b), interpolation=cv2.INTER_NEAREST)
+    region = np.zeros((height, width), np.uint8)
+    left, top = 0, 0
+    right, bottom = mrs.shape[1], mrs.shape[0]
+    an, bn, cn, dn = a, b, c, d
+    if a < 0:
+        left = -a
+        an = 0
+    if c > width:
+        right = mrs.shape[1] - (c - width)
+        cn = width
+    if b < 0:
+        top = -b
+        bn = 0
+    if d > height:
+        bottom = mrs.shape[0] - (d - height)
+        dn = height
+    region[bn:dn, an:cn] = mrs[top:bottom, left:right]
+    return region
+
+
+# --- luminance (image_utils.cpp:43-112) ---
+_SRGB_LUT = np.array([
+    ((v / 255.0) / 12.92) if (v / 255.0) <= 0.04045 else (((v / 255.0) + 0.055) / 1.055) ** 2.4
+    for v in range(256)
+], np.float64)
+
+
+def luminance(img_bgr: np.ndarray) -> np.ndarray:
+    """sRGB-linearized Rec.709 luma -> floor(y*255+0.5) uint8 (BGR input)."""
+    B = _SRGB_LUT[img_bgr[:, :, 0]]
+    G = _SRGB_LUT[img_bgr[:, :, 1]]
+    R = _SRGB_LUT[img_bgr[:, :, 2]]
+    y = 0.2126 * R + 0.7152 * G + 0.0722 * B
+    return np.floor(y * 255.0 + 0.5).astype(np.uint8)

ofiqpy-0.1.0/ofiqpy/batch.py

@@ -0,0 +1,102 @@
+"""Parallel batch runner — assess a directory of images to an OFIQ-format CSV.
+
+Each worker process builds its own pipeline (ONNX/cv2.ml models are not shared
+across processes). Resumable: rows already present in the output CSV are skipped.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import time
+from concurrent.futures import ProcessPoolExecutor
+from pathlib import Path
+
+import cv2
+
+from .output import header, row
+
+EXTS = {".jpg", ".jpeg", ".png", ".bmp"}
+
+# per-worker singletons
+_PIPE = None
+_MEAS = None
+
+
+def _init_worker():
+    global _PIPE, _MEAS
+    from .config import OFIQConfig
+    from .measures.core import Measures
+    from .pipeline import OFIQPipeline
+    cfg = OFIQConfig()
+    _PIPE = OFIQPipeline(cfg)
+    _MEAS = Measures(cfg)
+
+
+def _assess_one(path_str: str) -> str:
+    t0 = time.time()
+    bgr = cv2.imread(path_str)
+    try:
+        s = _PIPE.process(bgr)
+        res = _MEAS.compute(s) if s.bbox is not None else {}
+    except Exception:
+        res = {}
+    return row(path_str, res, (time.time() - t0) * 1000)
+
+
+def discover(input_path: Path) -> list[Path]:
+    p = Path(input_path)
+    if p.is_file():
+        return [p]
+    return sorted(f for f in p.rglob("*") if f.suffix.lower() in EXTS)
+
+
+def _already_done(out_csv: Path) -> set[str]:
+    if not out_csv.exists():
+        return set()
+    done = set()
+    with open(out_csv, newline="") as f:
+        r = csv.reader(f, delimiter=";")
+        next(r, None)  # header
+        for line in r:
+            if line:
+                done.add(line[0])
+    return done
+
+
+def run_batch(input_path, output_csv, workers=None, resume=False, progress=True):
+    images = discover(Path(input_path))
+    out = Path(output_csv)
+    done = _already_done(out) if resume else set()
+    todo = [im for im in images if im.name not in done]
+
+    write_header = not (resume and out.exists())
+    mode = "a" if (resume and out.exists()) else "w"
+    n_done = 0
+    t0 = time.time()
+    with open(out, mode) as fh, ProcessPoolExecutor(max_workers=workers,
+                                                    initializer=_init_worker) as ex:
+        if write_header:
+            fh.write(header() + "\n")
+        for line in ex.map(_assess_one, [str(im) for im in todo], chunksize=1):
+            fh.write(line + "\n")
+            fh.flush()
+            n_done += 1
+            if progress and n_done % 25 == 0:
+                rate = n_done / max(time.time() - t0, 1e-6)
+                print(f"  {n_done}/{len(todo)}  {rate:.1f} img/s", flush=True)
+    print(f"done: {n_done} images -> {out} ({len(done)} pre-existing skipped)")
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(description="ofiqpy parallel batch runner")
+    ap.add_argument("-i", "--input", required=True, help="image directory (recursive) or file")
+    ap.add_argument("-o", "--output", required=True, help="output CSV")
+    ap.add_argument("-w", "--workers", type=int, default=None, help="worker processes (default: CPUs)")
+    ap.add_argument("--resume", action="store_true", help="skip images already in the output CSV")
+    args = ap.parse_args()
+    run_batch(args.input, args.output, args.workers, args.resume)
+
+
+if __name__ == "__main__":
+    main()