ofiqpy 0.1.0__py3-none-any.whl

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/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/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()

ofiqpy/cli.py

@@ -0,0 +1,47 @@
+"""ofiqpy CLI — OFIQSampleApp-compatible: -i <file|dir> -o <out.csv>."""
+from __future__ import annotations
+
+import argparse
+import time
+from pathlib import Path
+
+import cv2
+
+from .config import OFIQConfig
+from .measures.core import Measures
+from .output import row, write_csv
+from .pipeline import OFIQPipeline
+
+EXTS = {".jpg", ".jpeg", ".png", ".bmp"}
+
+
+def main():
+    ap = argparse.ArgumentParser(description="ofiqpy — faithful OFIQ Python port")
+    ap.add_argument("-i", "--input", required=True, help="image file or directory")
+    ap.add_argument("-o", "--output", required=True, help="output CSV")
+    args = ap.parse_args()
+
+    inp = Path(args.input)
+    imgs = ([inp] if inp.is_file()
+            else sorted(p for p in inp.rglob("*") if p.suffix.lower() in EXTS))
+
+    cfg = OFIQConfig()
+    pipe = OFIQPipeline(cfg)
+    meas = Measures(cfg)
+
+    rows = []
+    for img in imgs:
+        t0 = time.time()
+        bgr = cv2.imread(str(img))
+        try:
+            s = pipe.process(bgr)
+            res = meas.compute(s) if s.bbox is not None else {}
+        except Exception:
+            res = {}
+        rows.append(row(str(img), res, (time.time() - t0) * 1000))
+    write_csv(args.output, rows)
+    print(f"wrote {args.output} ({len(rows)} images)")
+
+
+if __name__ == "__main__":
+    main()

ofiqpy/config.py

@@ -0,0 +1,101 @@
+"""OFIQ config loader — parses ofiq_config.jaxn and resolves model paths.
+
+Faithful port of OFIQ v1.1.0. Model files and config are reused directly from the
+reference OFIQ-Project checkout so the port loads the *same* weights OFIQ uses.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+# OFIQ's models + config are reused directly (they are separately licensed and NOT bundled).
+# Point ofiqpy at an OFIQ checkout's data/ directory via the OFIQPY_OFIQ_DATA env var, e.g.:
+#     export OFIQPY_OFIQ_DATA=/path/to/OFIQ-Project/data
+# Falls back to ./OFIQ-Project/data (relative to the current directory) if unset.
+_DEFAULT_DATA = Path("OFIQ-Project/data")
+OFIQ_DATA = Path(os.environ.get("OFIQPY_OFIQ_DATA", _DEFAULT_DATA))
+OFIQ_CONFIG = OFIQ_DATA / "ofiq_config.jaxn"
+
+
+def _strip_jaxn(text: str) -> str:
+    """Strip // and /* */ comments and trailing commas from JAXN, respecting strings."""
+    out = []
+    i, n = 0, len(text)
+    in_str = False
+    while i < n:
+        c = text[i]
+        if in_str:
+            out.append(c)
+            if c == "\\" and i + 1 < n:  # escape
+                out.append(text[i + 1])
+                i += 2
+                continue
+            if c == '"':
+                in_str = False
+            i += 1
+            continue
+        if c == '"':
+            in_str = True
+            out.append(c)
+            i += 1
+            continue
+        if c == "/" and i + 1 < n and text[i + 1] == "/":  # line comment
+            while i < n and text[i] != "\n":
+                i += 1
+            continue
+        if c == "/" and i + 1 < n and text[i + 1] == "*":  # block comment
+            i += 2
+            while i + 1 < n and not (text[i] == "*" and text[i + 1] == "/"):
+                i += 1
+            i += 2
+            continue
+        out.append(c)
+        i += 1
+    s = "".join(out)
+    # remove trailing commas before } or ]
+    import re
+
+    s = re.sub(r",(\s*[}\]])", r"\1", s)
+    return s
+
+
+def load_config(path: Path = OFIQ_CONFIG) -> dict:
+    raw = Path(path).read_text()
+    data = json.loads(_strip_jaxn(raw))
+    return data["config"]
+
+
+class OFIQConfig:
+    """Parsed OFIQ config with model-path resolution against the OFIQ data root."""
+
+    def __init__(self, path: Path = OFIQ_CONFIG, data_root: Path = OFIQ_DATA):
+        self.cfg = load_config(path)
+        self.data_root = Path(data_root)
+        self.params = self.cfg["params"]
+
+    def resolve(self, rel_path: str) -> Path:
+        p = self.data_root / rel_path
+        if not p.exists():
+            raise FileNotFoundError(f"OFIQ model not found: {p}")
+        return p
+
+    def measure(self, name: str) -> dict:
+        return self.params["measures"].get(name, {})
+
+    def sigmoid_params(self, measure: str) -> dict:
+        return self.measure(measure).get("Sigmoid", {})
+
+    def detector(self) -> dict:
+        return self.params["detector"]["ssd"]
+
+    def landmarks_model(self) -> Path:
+        return self.resolve(self.params["landmarks"]["ADNet"]["model_path"])
+
+
+if __name__ == "__main__":
+    c = OFIQConfig()
+    print("detector:", c.detector())
+    print("ADNet:", c.landmarks_model())
+    print("UnifiedQualityScore sigmoid:", c.sigmoid_params("UnifiedQualityScore"))
+    print("measures listed:", len(c.cfg["measures"]))

ofiqpy/detectors/ssd.py

@@ -0,0 +1,48 @@
+"""SSD face detector — faithful port of opencv_ssd_face_detector.cpp.
+
+Caffe model via OpenCV DNN (NOT onnxruntime): 300x300, BGR mean (104,117,123),
+pad 20%, conf>=0.4, min rel face size 0.05, primary = largest area.
+"""
+from __future__ import annotations
+
+import math
+
+import cv2
+import numpy as np
+
+
+def _round(x: float) -> int:
+    return int(math.copysign(math.floor(abs(x) + 0.5), x))
+
+
+class SSDDetector:
+    def __init__(self, caffemodel, prototxt, confidence_thr=0.4,
+                 min_rel_face_size=0.05, padding=0.2):
+        self.net = cv2.dnn.readNetFromCaffe(str(prototxt), str(caffemodel))
+        self.thr = confidence_thr
+        self.min_rel = min_rel_face_size
+        self.pad = padding
+
+    def detect(self, img: np.ndarray) -> list[tuple[int, int, int, int]]:
+        """Return face boxes [(left, top, w, h), ...] in ORIGINAL px, largest first."""
+        H, W = img.shape[:2]
+        padH = int(W * self.pad)   # static_cast truncation
+        padV = int(H * self.pad)
+        padded = cv2.copyMakeBorder(img, padV, padV, padH, padH,
+                                    cv2.BORDER_CONSTANT, value=(0, 0, 0))
+        Ph, Pw = padded.shape[:2]
+        blob = cv2.dnn.blobFromImage(padded, 1.0, (300, 300), (104, 117, 123),
+                                     swapRB=False, crop=False)
+        self.net.setInput(blob)
+        det = self.net.forward()  # (1,1,N,7)
+        faces = []
+        for row in det[0, 0]:
+            conf, l, t, r, b = float(row[2]), float(row[3]), float(row[4]), float(row[5]), float(row[6])
+            if conf >= self.thr and l > 0 and t > 0 and r < 1 and b < 1 and (r - l) > self.min_rel:
+                left = _round(l * Pw) - padH
+                top = _round(t * Ph) - padV
+                width = _round((r - l) * Pw)
+                height = _round((b - t) * Ph)
+                faces.append((left, top, width, height))
+        faces.sort(key=lambda f: f[2] * f[3], reverse=True)
+        return faces

ofiqpy/landmarks/adnet.py

@@ -0,0 +1,84 @@
+"""ADNet 98-point landmarks — faithful port of adnet_landmarks.cpp + utils.cpp squaring.
+
+ONNX input 'input' [1,3,256,256] BGR planes, norm 2p/255-1; output '3209' [1,98,2];
+denorm (v+1)/2*255; back-map to original px via square-box scale.
+"""
+from __future__ import annotations
+
+import math
+
+import cv2
+import numpy as np
+import onnxruntime as ort
+
+
+def _floor(x):
+    return int(math.floor(x))
+
+
+def _ceil(x):
+    return int(math.ceil(x))
+
+
+def _round(x):
+    return int(math.copysign(math.floor(abs(x) + 0.5), x))
+
+
+def make_square_bbox(left, top, w, h):
+    """utils.cpp:109-167 — extend the shorter side symmetrically to a square."""
+    xtl, ytl, xbr, ybr = left, top, left + w, top + h
+    if w < h:
+        xl = _floor((xbr + xtl - h) / 2.0)
+        xr = _ceil((xbr + xtl + h) / 2.0)
+        return xl, ytl, xr - xl, ybr - ytl  # (x, y, side, side)
+    else:
+        yt = _floor((ybr + ytl - w) / 2.0)
+        yb = _ceil((ybr + ytl + w) / 2.0)
+        return xtl, yt, xbr - xtl, yb - yt
+
+
+def make_square_with_padding(sq, img):
+    """utils.cpp:50-107 — pad image if the square box escapes bounds."""
+    x, y, sw, sh = sq
+    H, W = img.shape[:2]
+    xbr, ybr = x + sw, y + sh
+    top = max(0, -y)
+    bottom = max(0, ybr - H + 1)
+    left = max(0, -x)
+    right = max(0, xbr - W + 1)
+    if top or bottom or left or right:
+        padded = cv2.copyMakeBorder(img, top, bottom, left, right,
+                                    cv2.BORDER_CONSTANT, value=(0, 0, 0))
+    else:
+        padded = img
+    tx, ty = left, top
+    sq_pad = (x + tx, y + ty, sw, sh)
+    return padded, sq_pad, (tx, ty)
+
+
+class ADNetLandmarker:
+    def __init__(self, onnx_path):
+        self.sess = ort.InferenceSession(str(onnx_path), providers=["CPUExecutionProvider"])
+        self.out_name = "3209"
+
+    def extract(self, img: np.ndarray, primary_box) -> np.ndarray:
+        """img BGR uint8, primary_box=(left,top,w,h). Returns (98,2) original-px coords."""
+        sq = make_square_bbox(*primary_box)
+        padded, sq_pad, (tx, ty) = make_square_with_padding(sq, img)
+        x, y, sw, sh = sq_pad
+        crop = padded[y:y + sh, x:x + sw]
+        if crop.shape[:2] != (256, 256):
+            crop = cv2.resize(crop, (256, 256), interpolation=cv2.INTER_LINEAR)
+        arr = crop.astype(np.float32) * (2.0 / 255.0) - 1.0  # [-1,1], BGR planes
+        blob = np.transpose(arr, (2, 0, 1))[None]            # (1,3,256,256)
+        out = self.sess.run([self.out_name], {"input": blob})[0].reshape(-1)
+        out = (out + 1.0) / 2.0 * 255.0                      # denorm to 256-space
+        scale = sq[3] / 256.0    # OFIQ uses square HEIGHT/256 (adnet_landmarks.cpp:313),
+        #                          not width — the floor/ceil square can be 1px non-square.
+        ox = sq_pad[0] - tx                                   # original square xleft
+        oy = sq_pad[1] - ty
+        pts = np.empty((98, 2), np.float64)
+        for i in range(98):
+            pts[i, 0] = _round(out[2 * i] * scale + ox)
+            pts[i, 1] = _round(out[2 * i + 1] * scale + oy)
+        return pts