@camstack/addon-pipeline 1.2.291 → 1.2.293

package/python/inference_pool.py

@@ -1522,24 +1522,40 @@ def _to_model_tensor(arr: "np.ndarray", channels_last: bool) -> "np.ndarray":
 _IMAGENET_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
 _IMAGENET_STD = np.array([0.229, 0.224, 0.225], dtype=np.float32)
 
+# InsightFace's SCRFD input contract: upstream feeds `(pixel - 127.5) / 128`
+# ([-0.996, 0.996]), not the pool's historical plain `/255` ([0,1]). Expressed
+# against the pool's already-`/255` HWC array (`arr`, not raw pixels):
+#   (arr*255 - 127.5) / 128  ==  (arr - _SCRFD_MEAN) / _SCRFD_STD
+# with mean/std pre-divided by 255, the same shape of transform as the
+# ImageNet branch below. See `postprocessors/scrfd.py` for the upstream
+# citation and the measured effect (188 → 196 GT faces found,
+# 2026-09-26 model-replacement spike, §2.4-2).
+_SCRFD_MEAN = 127.5 / 255.0
+_SCRFD_STD = 128.0 / 255.0
+
 
 def _apply_normalization(arr: "np.ndarray", config: dict) -> "np.ndarray":
     """Apply per-model input normalization to an HWC RGB float array in [0,1].
 
-    Only ``inputNormalization == 'imagenet'`` changes anything: it subtracts the
-    ImageNet per-channel mean and divides by the std (RGB), matching the
-    EfficientNet-Lite0 / MobileNetV3 animal + vehicle classifiers whose
-    ``labels.json`` declares ``normalize: imagenet``. Absent / ``'none'`` /
-    ``'zero-one'`` keep the plain ``/255`` array byte-identical to the historical
-    unconditional path (detectors, CLIP/ArcFace, and the AIY bird classifier
-    which bakes its own scale). Runs on the HWC array BEFORE the optional
-    NHWC/NCHW transpose in :func:`_to_model_tensor`, so it is layout-agnostic
-    (channel axis is always last here). Pure numpy.
+    ``inputNormalization == 'imagenet'`` subtracts the ImageNet per-channel
+    mean and divides by the std (RGB), matching the EfficientNet-Lite0 /
+    MobileNetV3 animal + vehicle classifiers whose ``labels.json`` declares
+    ``normalize: imagenet``. ``'scrfd'`` applies InsightFace's SCRFD contract
+    (`_SCRFD_MEAN`/`_SCRFD_STD` above) — the `scrfd-2.5g` catalog entry.
+    Absent / ``'none'`` / ``'zero-one'`` keep the plain ``/255`` array
+    byte-identical to the historical unconditional path (most detectors,
+    CLIP/ArcFace, and the AIY bird classifier which bakes its own scale). Runs
+    on the HWC array BEFORE the optional NHWC/NCHW transpose in
+    :func:`_to_model_tensor`, so it is layout-agnostic (channel axis is always
+    last here). Pure numpy.
     """
-    if config.get("inputNormalization") != "imagenet":
+    mode = config.get("inputNormalization")
+    if mode not in ("imagenet", "scrfd"):
         return arr
     if arr.ndim != 3 or arr.shape[-1] != 3:
         return arr
+    if mode == "scrfd":
+        return (arr - _SCRFD_MEAN) / _SCRFD_STD
     return (arr - _IMAGENET_MEAN) / _IMAGENET_STD
 
 
@@ -1700,6 +1716,13 @@ def _build_ov_ppp_model(core: Any, path: str, config: dict) -> "tuple[Any, dict]
         steps.scale([255.0, 255.0, 255.0])
         steps.mean([float(v) for v in _IMAGENET_MEAN])
         steps.scale([float(v) for v in _IMAGENET_STD])
+    elif plan["normalization"] == "scrfd":
+        # ((x/255) - _SCRFD_MEAN) / _SCRFD_STD — InsightFace's SCRFD contract,
+        # folded the same way as the ImageNet branch above (see
+        # `_apply_normalization`/`_SCRFD_MEAN`/`_SCRFD_STD`).
+        steps.scale([255.0, 255.0, 255.0])
+        steps.mean([_SCRFD_MEAN, _SCRFD_MEAN, _SCRFD_MEAN])
+        steps.scale([_SCRFD_STD, _SCRFD_STD, _SCRFD_STD])
     else:
         steps.scale([255.0, 255.0, 255.0])
     built = ppp.build()

package/python/postprocessors/scrfd.py

@@ -1,7 +1,12 @@
 """SCRFD face detection postprocessor.
 
 Multi-stride anchor-based face detector (strides 8, 16, 32).
-Ported from packages/addon-vision/src/shared/postprocess/scrfd.ts.
+Originally ported from packages/addon-vision/src/shared/postprocess/scrfd.ts,
+whose Node.js raw-tensor onnxruntime path was retired in favour of doing all
+postprocessing here, in the Python inference pool — that TS file, and the
+addon-vision package it lived in, no longer exist (see the header comment in
+packages/addon-pipeline/src/detection-pipeline/postprocess/dispatch.ts). This
+module is now the sole SCRFD decoder in the repo.
 
 Output: {"kind": "detections", "detections": [{"class": "face", "score", "bbox": [x1,y1,x2,y2], "landmarks?"}]}
 """
@@ -13,13 +18,26 @@ NUM_ANCHORS_PER_STRIDE = 2
 
 
 def _generate_anchors(stride: int, input_size: int) -> list[tuple[float, float]]:
-    """Generate anchor centers for a given stride."""
+    """Generate anchor centers for a given stride.
+
+    Anchor centers are `(x * stride, y * stride)` — NO half-cell `+0.5` offset.
+    This matches upstream InsightFace's reference decoder exactly
+    (`insightface/model_zoo/scrfd.py`: `anchor_centers = np.stack([anchor_centers_x,
+    anchor_centers_y], axis=-1).astype(np.float32)`, built from a raw
+    `np.mgrid[:h, :w]` and then `anchor_centers * stride` — no `+0.5` anywhere
+    in that path). The previous `(x + 0.5) * stride` formula shifted every box
+    and landmark down-and-right by half a stride (4/8/16 px at 640), which is a
+    large fraction of a face after the letterbox upscale from a person crop.
+    Fixing this moved NME (COCO eyes+nose vs GT) 0.352 → 0.115 and AuraFace
+    self-consistency cosine 0.79 → 0.91 (2026-09-26 model-replacement spike,
+    docs/superpowers/specs/2026-09-26-replacement-models-spike.md §2.4-1).
+    """
     feat_size = int(np.ceil(input_size / stride))
     anchors = []
     for y in range(feat_size):
         for x in range(feat_size):
             for _ in range(NUM_ANCHORS_PER_STRIDE):
-                anchors.append(((x + 0.5) * stride, (y + 0.5) * stride))
+                anchors.append((x * stride, y * stride))
     return anchors
 
 

package/python/postprocessors/test_scrfd.py

@@ -0,0 +1,151 @@
+"""Pins SCRFD's anchor-center placement to InsightFace's upstream convention.
+
+The production defect (2026-09-26 model-replacement spike,
+docs/superpowers/specs/2026-09-26-replacement-models-spike.md §2.4-1): anchor
+centers were computed as `(x + 0.5) * stride` (a "half-cell" YOLO-style
+offset). Upstream InsightFace (`insightface/model_zoo/scrfd.py`) uses
+`x * stride` — no half-cell. The offset shifted every box and landmark
+down-and-right by half a stride (4/8/16 px at 640), degrading alignment and
+therefore face-recognition accuracy on every install. Fixing it moved NME
+(COCO eyes+nose GT) 0.352 → 0.115.
+
+`unittest.TestCase`, not pytest-style: `scripts/test-python-pool.sh` classifies
+test modules by content and runs the `unittest.TestCase` ones on the bare
+interpreter (no pytest) — the path CI actually exercises
+(`.github/workflows/ci.yml` `Test the inference pool (python)` step). Real
+numpy when present; only `np.ceil` is stubbed on `ImportError` so `scrfd.py`
+still imports and `_generate_anchors` (no ndarray ops, just scalar `np.ceil`)
+still runs correctly — the anchor-formula regression is caught either way. The
+fuller `postprocess_scrfd` round trip needs real ndarray behaviour a stub
+cannot reasonably fake, so it is skipped (not silently passed) without real
+numpy.
+"""
+import math
+import sys
+import types
+import unittest
+
+try:  # real numpy when the sandbox has it
+    import numpy as _numpy_probe  # noqa: F401
+except ImportError:
+    _numpy_probe = None
+
+# `import numpy` can SUCCEED against a MINIMAL STUB another test module in
+# this same `python3 -m unittest` process already installed (this file's own
+# `postprocessors/` subprocess currently runs alone, but this is the same
+# defensive check `test_inference_pool_scrfd_normalization.py` needs — a bare
+# "did the import raise" check is not reliable once more than one stubbing
+# test module shares a process). `ndarray` is real-numpy-only.
+_HAS_REAL_NUMPY = _numpy_probe is not None and hasattr(_numpy_probe, "ndarray")
+if _numpy_probe is None:
+    _np = types.ModuleType("numpy")
+    _np.ceil = math.ceil  # the only numpy call `_generate_anchors` makes
+    sys.modules["numpy"] = _np
+
+from scrfd import _generate_anchors, postprocess_scrfd  # noqa: E402
+
+
+class AnchorCentersHaveNoHalfCellOffsetTest(unittest.TestCase):
+    """Numpy-independent: `_generate_anchors` only calls `np.ceil` on a
+    scalar, so this runs — and catches the regression — with or without real
+    numpy installed."""
+
+    def test_first_anchor_sits_at_the_pixel_origin(self):
+        # stride=8, input_size=16 → feat_size=2 → grid x,y in {0,1}. The FIRST
+        # anchor center (grid cell 0,0) must sit at the pixel origin (0,0),
+        # not at the half-cell (4,4) the old `(x+0.5)*stride` formula
+        # produced.
+        anchors = _generate_anchors(stride=8, input_size=16)
+        self.assertEqual(anchors[0], (0.0, 0.0))
+        self.assertEqual(anchors[1], (0.0, 0.0))  # NUM_ANCHORS_PER_STRIDE=2
+
+    def test_anchor_centers_match_upstream_grid_exactly(self):
+        stride, input_size = 16, 32  # feat_size = 2
+        anchors = _generate_anchors(stride, input_size)
+        # Upstream: anchor_centers = mgrid(feat, feat) * stride — plain
+        # multiples of stride, row-major (y outer, x inner), 2 anchors/cell.
+        expected = []
+        for y in range(2):
+            for x in range(2):
+                expected.append((x * stride, y * stride))
+                expected.append((x * stride, y * stride))
+        self.assertEqual(anchors, expected)
+        # The rejected half-cell formula would have placed the first center
+        # at (8.0, 8.0), not (0.0, 0.0) — the exact regression this test
+        # would catch if `_generate_anchors` reverted to `(x + 0.5) * stride`.
+        self.assertNotEqual(anchors[0], (stride / 2, stride / 2))
+
+
+def _single_anchor_output(np_mod, stride: int, input_size: int, box_offsets, kps_offsets=None):
+    """Build a raw SCRFD-shaped output with exactly ONE live anchor (grid cell
+    0,0, first of the two anchors), all others below threshold. Needs real
+    ndarray behaviour, so only called from the real-numpy-gated tests below."""
+    feat = int(np_mod.ceil(input_size / stride))
+    n = feat * feat * 2
+    scores = np_mod.zeros((n, 1), dtype=np_mod.float32)
+    scores[0, 0] = 0.99
+    bboxes = np_mod.zeros((n, 4), dtype=np_mod.float32)
+    bboxes[0] = box_offsets
+    out = {f"score_{stride}": scores, f"bbox_{stride}": bboxes}
+    if kps_offsets is not None:
+        kps = np_mod.zeros((n, 10), dtype=np_mod.float32)
+        kps[0] = kps_offsets
+        out[f"kps_{stride}"] = kps
+    return out
+
+
+@unittest.skipUnless(_HAS_REAL_NUMPY, "postprocess_scrfd round trip needs real ndarray ops")
+class PostprocessScrfdRoundTripTest(unittest.TestCase):
+    def setUp(self):
+        import numpy as np
+
+        self.np = np
+
+    def test_box_position_uses_unshifted_anchor_center(self):
+        # Grid cell (0,0) at stride 8 → anchor center (0,0) after the fix. A
+        # symmetric box offset of 5 stride-units around the anchor center
+        # lands the box at [0, 0, 40, 40] pre-clamp on the un-clamped side.
+        stride, input_size = 8, 640
+        raw = _single_anchor_output(self.np, stride, input_size, box_offsets=[5.0, 5.0, 5.0, 5.0])
+        out = postprocess_scrfd(
+            raw,
+            {"confidence": 0.5, "inputSize": input_size, "strides": [stride]},
+            orig_w=1000,
+            orig_h=1000,
+            scale=1.0,
+            pad=(0, 0),
+        )
+        dets = out["detections"]
+        self.assertEqual(len(dets), 1)
+        _x1, _y1, x2, y2 = dets[0]["bbox"]
+        self.assertEqual(x2, 40.0)  # 0 + 5*8
+        self.assertEqual(y2, 40.0)
+        # With the OLD (x+0.5)*stride formula the anchor center would have
+        # been (4, 4) and x2/y2 would be 44.0, not 40.0 — the regression
+        # guard.
+        self.assertNotEqual(x2, 44.0)
+
+    def test_landmarks_use_unshifted_anchor_center(self):
+        stride, input_size = 16, 640
+        kps = [1.0, 1.0] * 5  # 5 landmarks, each offset (1,1) stride-units
+        raw = _single_anchor_output(
+            self.np, stride, input_size, box_offsets=[1.0, 1.0, 1.0, 1.0], kps_offsets=kps
+        )
+        out = postprocess_scrfd(
+            raw,
+            {"confidence": 0.5, "inputSize": input_size, "strides": [stride]},
+            orig_w=1000,
+            orig_h=1000,
+            scale=1.0,
+            pad=(0, 0),
+        )
+        dets = out["detections"]
+        self.assertEqual(len(dets), 1)
+        for p in dets[0]["landmarks"]:
+            # anchor (0,0) + 1*stride = 16, not 8 (the half-cell) + 16 = 24.
+            self.assertEqual(p["x"], 16.0)
+            self.assertEqual(p["y"], 16.0)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/test_inference_pool_ov_ppp_scrfd.py

@@ -0,0 +1,264 @@
+"""Pins the OpenVINO PPP fold's `'scrfd'` branch (`_build_ov_ppp_model`,
+`inference_pool.py` ~1719) — the code path that folds InsightFace's SCRFD
+input contract (`(x-127.5)/128`) into a compiled OpenVINO graph, mirrored
+against `_apply_normalization`'s plain-Python path (covered separately by
+`test_inference_pool_scrfd_normalization.py`).
+
+`_ov_ppp_plan` (tested elsewhere) only proves the CONFIG VALUE `'scrfd'`
+reaches a plan dict — it does not touch `_build_ov_ppp_model`'s actual
+`elif plan["normalization"] == "scrfd":` branch, so renaming or deleting that
+branch (falling through to the `else` — plain `/255`, no shift) would leave
+every other test green. This file drives `_build_ov_ppp_model` itself and
+asserts the exact preprocessing STEPS it records for `'scrfd'`.
+
+No real OpenVINO install needed: `openvino` / `openvino.preprocess` are
+FAKE modules that record every `PrePostProcessor` call instead of running one,
+built fresh in `setUp` and removed in `tearDown` so nothing leaks into a
+sibling test run in the same `python3 -m unittest` process (this repo's own
+warning: "a blind stub POISONS the whole session"). If real `openvino` is
+importable, this test still uses its own fakes (swapped in for the duration
+of the test only) rather than depending on optional real behaviour — so it
+runs the same way whether or not OpenVINO is installed.
+
+`unittest.TestCase`, not pytest-style — runs on the bare interpreter, no
+pytest needed (`scripts/test-python-pool.sh`, the path CI exercises).
+"""
+import sys
+import types
+import unittest
+
+try:  # real numpy when the sandbox has it — a blind stub POISONS the whole
+    import numpy  # noqa: F401  # pytest session for every sibling that needs it
+except ImportError:
+    _np = types.ModuleType("numpy")
+    _np.array = lambda seq, dtype=None: list(seq)  # noqa: E731
+    _np.float32 = "float32"
+    sys.modules["numpy"] = _np
+try:  # real PIL when present, for the same reason
+    import PIL.Image  # noqa: F401
+except ImportError:
+    _pil = types.ModuleType("PIL")
+    _pil_image = types.ModuleType("PIL.Image")
+    _pil.Image = _pil_image
+    sys.modules["PIL"] = _pil
+    sys.modules["PIL.Image"] = _pil_image
+if "postprocessors" not in sys.modules:
+    _pp = types.ModuleType("postprocessors")
+    _pp.POSTPROCESSORS = {}
+    sys.modules["postprocessors"] = _pp
+
+import inference_pool  # noqa: E402
+from inference_pool import _SCRFD_MEAN, _SCRFD_STD, _build_ov_ppp_model  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Fakes standing in for the real `openvino` / `openvino.preprocess` API
+# surface `_build_ov_ppp_model` calls. Each records the calls made on it.
+# ---------------------------------------------------------------------------
+
+
+class _FakeSteps:
+    """Stands in for OpenVINO's `PreProcessSteps` — every call is recorded,
+    in order, so the test can assert the EXACT scale/mean sequence."""
+
+    def __init__(self, calls: list) -> None:
+        self._calls = calls
+
+    def convert_element_type(self, t):
+        self._calls.append(("convert_element_type", t))
+        return self
+
+    def scale(self, v):
+        self._calls.append(("scale", tuple(v)))
+        return self
+
+    def mean(self, v):
+        self._calls.append(("mean", tuple(v)))
+        return self
+
+
+class _FakeTensorInfo:
+    def set_element_type(self, t):
+        return self
+
+    def set_layout(self, layout):
+        return self
+
+
+class _FakeModelInfo:
+    def set_layout(self, layout):
+        return self
+
+
+class _FakeInputInfo:
+    def __init__(self, calls: list) -> None:
+        self._steps = _FakeSteps(calls)
+
+    def tensor(self):
+        return _FakeTensorInfo()
+
+    def model(self):
+        return _FakeModelInfo()
+
+    def preprocess(self):
+        return self._steps
+
+
+class _FakePrePostProcessor:
+    """Records every preprocessing step applied, keyed by the model it was
+    built for — `_build_ov_ppp_model` builds exactly one per call."""
+
+    last_calls: "list | None" = None
+
+    def __init__(self, model) -> None:
+        self._calls: list = []
+        _FakePrePostProcessor.last_calls = self._calls
+        self._input = _FakeInputInfo(self._calls)
+
+    def input(self):
+        return self._input
+
+    def build(self):
+        return "BUILT_MODEL"
+
+
+class _FakeLayout:
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+
+class _FakeType:
+    u8 = "u8"
+    f32 = "f32"
+
+
+class _FakeDim:
+    """Mimics an OpenVINO static Dimension (see `test_inference_pool_ov_ppp.py`)."""
+
+    def __init__(self, length: int) -> None:
+        self._length = length
+        self.is_static = True
+
+    def __int__(self) -> int:
+        raise TypeError("Dimension is not directly int()-able")
+
+    def get_length(self) -> int:
+        return self._length
+
+
+class _FakeInput:
+    def __init__(self, dims) -> None:
+        self._dims = dims
+
+    def get_partial_shape(self):
+        return self._dims
+
+
+class _FakeModel:
+    def __init__(self, dims) -> None:
+        self._input = _FakeInput(dims)
+
+    def input(self):
+        return self._input
+
+
+class _FakeCore:
+    def __init__(self, dims) -> None:
+        self._dims = dims
+
+    def read_model(self, path):
+        return _FakeModel(self._dims)
+
+
+# A standard 640x640 NCHW 3-channel static-shape detector input — the shape
+# `_ov_ppp_plan` requires to fold preprocessing at all.
+_NCHW_640_DIMS = [_FakeDim(1), _FakeDim(3), _FakeDim(640), _FakeDim(640)]
+
+
+class BuildOvPppModelScrfdBranchTest(unittest.TestCase):
+    def setUp(self):
+        # Swap in the fakes for the duration of this test ONLY, whether or
+        # not real openvino/openvino.preprocess were already in sys.modules —
+        # restored in tearDown so nothing leaks into a sibling test run in
+        # the same `python3 -m unittest` process.
+        self._saved_openvino = sys.modules.get("openvino")
+        self._saved_openvino_preprocess = sys.modules.get("openvino.preprocess")
+
+        fake_openvino = types.ModuleType("openvino")
+        fake_openvino.Layout = _FakeLayout
+        fake_openvino.Type = _FakeType
+        fake_preprocess = types.ModuleType("openvino.preprocess")
+        fake_preprocess.PrePostProcessor = _FakePrePostProcessor
+        fake_openvino.preprocess = fake_preprocess
+
+        sys.modules["openvino"] = fake_openvino
+        sys.modules["openvino.preprocess"] = fake_preprocess
+
+    def tearDown(self):
+        for name, saved in (
+            ("openvino", self._saved_openvino),
+            ("openvino.preprocess", self._saved_openvino_preprocess),
+        ):
+            if saved is None:
+                sys.modules.pop(name, None)
+            else:
+                sys.modules[name] = saved
+
+    def test_scrfd_branch_applies_the_scrfd_mean_and_std(self):
+        core = _FakeCore(_NCHW_640_DIMS)
+        config = {
+            "inputSize": 640,
+            "inputWidth": 640,
+            "inputHeight": 640,
+            "inputChannels": 3,
+            "preprocessMode": "letterbox",
+            "inputNormalization": "scrfd",
+        }
+        built, plan = _build_ov_ppp_model(core, "dummy-path", config)
+        self.assertEqual(built, "BUILT_MODEL")
+        self.assertEqual(plan["normalization"], "scrfd")
+
+        calls = _FakePrePostProcessor.last_calls
+        # convert_element_type, then scale(255) → mean(_SCRFD_MEAN) →
+        # scale(_SCRFD_STD) — exactly 4 recorded steps, in this order. If the
+        # 'scrfd' branch is removed (falling to the bare `else: scale(255)`),
+        # this drops to 2 steps and the assertion below fails.
+        self.assertEqual(
+            calls,
+            [
+                ("convert_element_type", "f32"),
+                ("scale", (255.0, 255.0, 255.0)),
+                ("mean", (_SCRFD_MEAN, _SCRFD_MEAN, _SCRFD_MEAN)),
+                ("scale", (_SCRFD_STD, _SCRFD_STD, _SCRFD_STD)),
+            ],
+        )
+
+    def test_scrfd_branch_is_distinct_from_imagenet_and_none(self):
+        core = _FakeCore(_NCHW_640_DIMS)
+
+        def steps_for(normalization):
+            config = {
+                "inputSize": 640,
+                "inputWidth": 640,
+                "inputHeight": 640,
+                "inputChannels": 3,
+                "preprocessMode": "letterbox",
+                "inputNormalization": normalization,
+            }
+            _build_ov_ppp_model(core, "dummy-path", config)
+            return _FakePrePostProcessor.last_calls
+
+        scrfd_calls = steps_for("scrfd")
+        imagenet_calls = steps_for("imagenet")
+        none_calls = steps_for(None)
+
+        self.assertEqual(len(scrfd_calls), 4)
+        self.assertEqual(len(imagenet_calls), 4)
+        self.assertEqual(len(none_calls), 2)  # convert_element_type + scale(255) only
+        self.assertNotEqual(scrfd_calls, imagenet_calls)
+        # The imagenet branch uses the real _IMAGENET_MEAN/_STD, not SCRFD's.
+        self.assertNotIn(("mean", (_SCRFD_MEAN, _SCRFD_MEAN, _SCRFD_MEAN)), imagenet_calls)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/test_inference_pool_scrfd_normalization.py

@@ -0,0 +1,142 @@
+"""Pins the SCRFD input-normalization contract (`inputNormalization: 'scrfd'`).
+
+The production defect (2026-09-26 model-replacement spike,
+docs/superpowers/specs/2026-09-26-replacement-models-spike.md §2.4-2): the
+pool fed SCRFD the historical plain `/255` ([0,1]) tensor, but upstream
+InsightFace expects `(pixel - 127.5) / 128` ([-0.996, 0.996]). The re-hosted
+ONNX/OpenVINO/CoreML artifacts are unmodified upstream graphs (first op is a
+Conv — nothing absorbs the shift), so this has to be threaded through the
+runtime preprocessor rather than baked into the graph (contrast with
+AuraFace/CLIP, whose graphs bake their own normalization).
+
+This one contract, `_apply_normalization`, is the SAME function the ONNX path
+and the CoreML `multiArrayType` path both call — verified 2026-09-26 that the
+hosted `camstack-scrfd-2.5g.mlpackage`'s input is `multiArrayType`, not
+`imageType`, so it goes through this same function. The OpenVINO PPP fast
+path (`_build_ov_ppp_model`) folds the identical scale/mean/scale sequence
+into the compiled graph instead (covered separately, without needing a real
+OpenVINO install, by `test_inference_pool_ov_ppp_scrfd.py`), and is mutually
+exclusive with `_apply_normalization` (`_preprocess` returns early on the PPP
+fast path, `inference_pool.py` ~1828) — so there is no double application on
+any backend.
+
+`unittest.TestCase`, not pytest-style: `scripts/test-python-pool.sh` runs the
+`unittest.TestCase` modules on the bare interpreter (no pytest) — the path CI
+actually exercises. Heavy deps (numpy/PIL/postprocessors) are stubbed on
+`ImportError`, the same pattern as `test_inference_pool_ov_ppp.py`, so the
+module always imports; the tests that need real ndarray arithmetic are
+skipped (not silently passed) without real numpy, while the ones that don't
+(the constants pin, and `_ov_ppp_plan`'s pure config threading) always run.
+
+Run: python3 -m unittest test_inference_pool_scrfd_normalization -v
+"""
+import sys
+import types
+import unittest
+
+try:  # real numpy when the sandbox has it — a blind stub POISONS the whole
+    import numpy as _numpy_probe  # noqa: F401  # session for every sibling that needs it
+except ImportError:
+    _numpy_probe = None
+
+# `import numpy` can SUCCEED against a MINIMAL STUB another test module in
+# this same `python3 -m unittest` process already installed into
+# `sys.modules['numpy']` (`test_inference_pool_ov_ppp.py` and siblings do the
+# same guard) — a bare "did the import raise" check would then wrongly treat
+# that stub as real numpy and crash on the first `arr.ndim` access. `ndarray`
+# is real-numpy-only (no stub in this file tree defines it), so check for it
+# instead of trusting import success alone.
+_HAS_REAL_NUMPY = _numpy_probe is not None and hasattr(_numpy_probe, "ndarray")
+if _numpy_probe is None:
+    _np = types.ModuleType("numpy")
+    # `inference_pool` builds `_IMAGENET_MEAN = np.array(...)` at import time.
+    _np.array = lambda seq, dtype=None: list(seq)  # noqa: E731
+    _np.float32 = "float32"
+    sys.modules["numpy"] = _np
+try:  # real PIL when present, for the same reason
+    import PIL.Image  # noqa: F401
+except ImportError:
+    _pil = types.ModuleType("PIL")
+    _pil_image = types.ModuleType("PIL.Image")
+    _pil.Image = _pil_image
+    sys.modules["PIL"] = _pil
+    sys.modules["PIL.Image"] = _pil_image
+if "postprocessors" not in sys.modules:
+    _pp = types.ModuleType("postprocessors")
+    _pp.POSTPROCESSORS = {}
+    sys.modules["postprocessors"] = _pp
+
+import inference_pool  # noqa: E402
+from inference_pool import (  # noqa: E402
+    _SCRFD_MEAN,
+    _SCRFD_STD,
+    _apply_normalization,
+    _ov_ppp_plan,
+)
+
+
+class ScrfdNormalizationConstantsTest(unittest.TestCase):
+    """Plain floats, no ndarray ops — always runs, with or without numpy."""
+
+    def test_constants_match_upstream_formula(self):
+        # _SCRFD_MEAN/_SCRFD_STD are the pool's own pre-divided-by-255
+        # constants; cross-check them against the raw-pixel upstream formula
+        # `(pixel - 127.5) / 128` directly, so a future edit to either
+        # constant is caught here rather than only in the end-to-end face
+        # count.
+        self.assertAlmostEqual(_SCRFD_MEAN, 127.5 / 255.0)
+        self.assertAlmostEqual(_SCRFD_STD, 128.0 / 255.0)
+
+
+class OvPppPlanThreadsScrfdTest(unittest.TestCase):
+    """`_ov_ppp_plan` is pure Python (no numpy) — always runs."""
+
+    def test_scrfd_normalization_reaches_the_plan(self):
+        plan = _ov_ppp_plan(
+            dims=[1, 3, 640, 640],
+            input_channels=3,
+            preprocess_mode="letterbox",
+            normalization="scrfd",
+            enabled=True,
+        )
+        self.assertIsNotNone(plan)
+        self.assertEqual(plan["normalization"], "scrfd")
+
+
+@unittest.skipUnless(_HAS_REAL_NUMPY, "_apply_normalization needs real ndarray ops")
+class ApplyNormalizationScrfdTest(unittest.TestCase):
+    def setUp(self):
+        import numpy as np
+
+        self.np = np
+
+    def _flat_hwc(self, value: float):
+        """A 1x1 HWC array holding a single already-`/255` pixel value."""
+        return self.np.array([[[value, value, value]]], dtype=self.np.float32)
+
+    def test_scrfd_mode_matches_upstream_formula_at_pixel_extremes(self):
+        # Upstream, on raw pixels: (pixel - 127.5) / 128.
+        # pixel=0   → -0.99609375 ; pixel=255 → 0.99609375 ; pixel=127.5 → 0.0
+        for pixel, expected in [(0.0, -0.99609375), (255.0, 0.99609375), (127.5, 0.0)]:
+            arr = self._flat_hwc(pixel / 255.0)
+            out = _apply_normalization(arr, {"inputNormalization": "scrfd"})
+            self.assertEqual(out.shape, arr.shape)
+            self.assertAlmostEqual(float(out[0, 0, 0]), expected, places=6)
+
+    def test_absent_and_none_and_zero_one_are_unchanged(self):
+        arr = self._flat_hwc(0.6)
+        for config in ({}, {"inputNormalization": "none"}, {"inputNormalization": "zero-one"}):
+            out = _apply_normalization(arr, config)
+            self.assertTrue(self.np.array_equal(out, arr))
+
+    def test_imagenet_mode_is_unaffected_by_the_scrfd_branch(self):
+        # Regression guard: adding the 'scrfd' branch must not perturb the
+        # existing 'imagenet' branch (animal/vehicle classifiers).
+        arr = self._flat_hwc(0.5)
+        out = _apply_normalization(arr, {"inputNormalization": "imagenet"})
+        expected = (arr - inference_pool._IMAGENET_MEAN) / inference_pool._IMAGENET_STD
+        self.assertTrue(self.np.allclose(out, expected))
+
+
+if __name__ == "__main__":
+    unittest.main()