@camstack/addon-pipeline 1.2.294 → 1.2.296

package/python/postprocessors/ssd.py

@@ -14,10 +14,25 @@ The inference_pool ``edgetpu`` predict closure returns them keyed by their
 positional output index ("0".."3"). Output matches the yolo postprocessor:
 ``{"kind": "detections", "detections": [{"class", "score", "bbox":[x1,y1,x2,y2]}]}``
 with pixel bboxes in ORIGINAL frame coordinates.
+
+The same layout, verified per model on the upstream graph (2026-09-26):
+
+    ssd-mobilenet-v2-coco-edgetpu    300x300 uint8, N=20
+    efficientdet-lite0-edgetpu       320x320 uint8, N=25
+    ssdlite-mobiledet-coco-edgetpu   320x320 uint8, N=100, 91 score columns
+                                     (background + COCO-90), so the emitted
+                                     class index is already 0-based: 0 = person
+
+The decode is plain Python over nested lists. Each tensor is turned into a list
+once (``ndarray.tolist()``), so this module needs no numpy: CI's self-hosted
+runner has none, and the MobileDet fixture test (``test_ssd.py``) must run
+there, not be skipped there. Measured: ~85 µs per frame against ~14 µs for
+the old numpy decode (about 6×), under 1% of a core at 100 fps and small next
+to a ~9 ms Coral invoke.
 """
 from __future__ import annotations
 
-import numpy as np
+from typing import Any
 
 # Coral COCO 90-class label map (github.com/google-coral/test_data coco_labels.txt).
 # The "n/a" placeholders keep the raw model class indices aligned and are skipped.
@@ -38,6 +53,40 @@ COCO_90 = [
 ]
 
 
+def _as_list(value: Any) -> Any:
+    """A tensor as nested Python lists (a scalar stays a scalar)."""
+    return value.tolist() if hasattr(value, "tolist") else value
+
+
+def _shape(value: Any) -> tuple:
+    """numpy-style shape of a nested list; ``()`` for a scalar."""
+    dims: list[int] = []
+    while isinstance(value, (list, tuple)):
+        dims.append(len(value))
+        if not value:
+            break
+        value = value[0]
+    return tuple(dims)
+
+
+def _flatten(value: Any) -> list:
+    """Every scalar of a nested list, in row-major order (``reshape(-1)``)."""
+    if not isinstance(value, (list, tuple)):
+        return [value]
+    flat: list = []
+    for item in value:
+        flat.extend(_flatten(item))
+    return flat
+
+
+def _rows_of_4(value: Any) -> list:
+    """``reshape(-1, 4)`` of a nested list; refuses a size numpy would refuse."""
+    flat = _flatten(value)
+    if len(flat) % 4 != 0:
+        raise ValueError(f"cannot reshape {len(flat)} box values into rows of 4")
+    return [flat[i:i + 4] for i in range(0, len(flat), 4)]
+
+
 def _split_outputs(predictions: dict) -> tuple:
     """Resolve (boxes, classes, scores, count) from the raw prediction dict.
 
@@ -46,20 +95,22 @@ def _split_outputs(predictions: dict) -> tuple:
     """
     if all(k in predictions for k in ("0", "1", "2", "3")):
         return (
-            np.asarray(predictions["0"]),
-            np.asarray(predictions["1"]),
-            np.asarray(predictions["2"]),
-            np.asarray(predictions["3"]),
+            _as_list(predictions["0"]),
+            _as_list(predictions["1"]),
+            _as_list(predictions["2"]),
+            _as_list(predictions["3"]),
         )
-    vals = [np.asarray(v) for v in predictions.values()]
+    vals = [_as_list(v) for v in predictions.values()]
     boxes = count = None
-    two_d: list[np.ndarray] = []
+    two_d: list = []
     for v in vals:
-        if v.ndim >= 2 and v.shape[-1] == 4:
+        shape = _shape(v)
+        ndim = len(shape)
+        if ndim >= 2 and shape[-1] == 4:
             boxes = v
-        elif v.ndim == 1 or (v.ndim == 2 and v.shape[-1] == 1):
+        elif ndim == 1 or (ndim == 2 and shape[-1] == 1):
             count = v
-        elif v.ndim == 2:
+        elif ndim == 2:
             two_d.append(v)
     # TFLite_Detection_PostProcess emits classes BEFORE scores.
     classes = two_d[0] if len(two_d) > 0 else None
@@ -67,6 +118,11 @@ def _split_outputs(predictions: dict) -> tuple:
     return boxes, classes, scores, count
 
 
+def label_for_class(cls: int) -> str:
+    """COCO-90 label of a raw class index; ``"n/a"`` for a gap, ``str`` if outside."""
+    return COCO_90[cls] if 0 <= cls < len(COCO_90) else str(cls)
+
+
 def postprocess_ssd(
     predictions: dict,
     config: dict,
@@ -83,12 +139,13 @@ def postprocess_ssd(
     if boxes is None or scores is None:
         return {"kind": "detections", "detections": []}
 
-    boxes = boxes.reshape(-1, 4)
-    scores = scores.reshape(-1)
-    classes = classes.reshape(-1) if classes is not None else np.zeros_like(scores)
+    boxes = _rows_of_4(boxes)
+    scores = _flatten(scores)
+    classes = _flatten(classes) if classes is not None else [0.0] * len(scores)
     n = len(scores)
-    if count is not None and count.size:
-        n = min(n, int(count.reshape(-1)[0]))
+    count_flat = _flatten(count) if count is not None else []
+    if count_flat:
+        n = min(n, int(count_flat[0]))
     n = min(n, len(boxes), len(classes))
 
     pad_x, pad_y = pad
@@ -115,8 +172,7 @@ def postprocess_ssd(
         y2 = max(0.0, min(y2, orig_h))
         if x2 <= x1 or y2 <= y1:
             continue
-        cls = int(classes[i])
-        label = COCO_90[cls] if 0 <= cls < len(COCO_90) else str(cls)
+        label = label_for_class(int(classes[i]))
         if label == "n/a":
             continue
         detections.append({

package/python/postprocessors/test_ssd.py

@@ -0,0 +1,205 @@
+"""Pins the SSD decoder on REAL SSDLite MobileDet output tensors.
+
+`ssdlite-mobiledet-coco-edgetpu` joins the two Coral detectors that already use
+`postprocessor: 'ssd'`. Its graph ends in the same `TFLite_Detection_PostProcess`
+op, but nothing had checked that the decoder reads MobileDet's outputs the way
+the model writes them. Each class below pins one thing that could silently turn
+a working model into wrong labels or empty frames:
+
+- the output ORDER (boxes, classes, scores, count on positional keys "0".."3");
+- the class-index OFFSET (91 score columns, background dropped by the op, so
+  the emitted index is 0-based and 0 is person);
+- the COUNT clamp (MobileDet emits N=100 rows, not 20 like SSD MobileNet V2);
+- the letterbox inversion, against boxes an unrelated detector (DETR) drew on
+  the same COCO frame;
+- the score CEILING of this quantised graph (about 0.771), which decides which
+  confidence thresholds can ever pass.
+
+The fixture (`testdata/ssdlite_mobiledet_outputs.json`) holds the model's raw
+outputs on two COCO val2017 frames; its `_provenance` says how they were made.
+
+`unittest.TestCase` with no numpy: `scripts/test-python-pool.sh` runs these on
+CI's bare interpreter, where numpy is absent, and `ssd.py` decodes plain lists
+for exactly that reason. The one case that needs numpy (ndarray inputs decode
+the same as lists) is skipped, by name, without it.
+"""
+import json
+import os
+import unittest
+
+try:  # real numpy when the sandbox has it
+    import numpy as _numpy_probe
+except ImportError:
+    _numpy_probe = None
+
+# `ndarray` is real-numpy-only: a stub another test module installed would import.
+_HAS_REAL_NUMPY = _numpy_probe is not None and hasattr(_numpy_probe, "ndarray")
+
+from ssd import COCO_90, label_for_class, postprocess_ssd  # noqa: E402
+
+_FIXTURE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "testdata",
+                        "ssdlite_mobiledet_outputs.json")
+with open(_FIXTURE, encoding="utf-8") as _fh:
+    _FRAMES = json.load(_fh)["frames"]
+
+CATS = _FRAMES["coco_val2017_000000039769_two_cats"]
+STREET = _FRAMES["coco_val2017_000000252219_street"]
+
+# The catalog entry's input side; the pool sets `inputSize` from the graph.
+INPUT_SIZE = 320
+# The score column of this graph is LOGISTIC over a uint8 logit quantised at
+# scale 0.046695, zero point 229, so the largest logit it can carry is
+# (255 - 229) * 0.046695 = 1.2141 and sigmoid(1.2141) = 0.77102.
+SCORE_CEILING = 0.77102
+
+
+def _decode(frame: dict, confidence: float = 0.5, outputs: "dict | None" = None) -> list:
+    width, height = frame["orig"]
+    result = postprocess_ssd(
+        outputs if outputs is not None else frame["outputs"],
+        {"confidence": confidence, "inputSize": INPUT_SIZE},
+        width, height, frame["scale"], tuple(frame["pad"]),
+    )
+    return result["detections"]
+
+
+def _iou(a: list, b: list) -> float:
+    ix = max(0.0, min(a[2], b[2]) - max(a[0], b[0]))
+    iy = max(0.0, min(a[3], b[3]) - max(a[1], b[1]))
+    inter = ix * iy
+    union = (a[2] - a[0]) * (a[3] - a[1]) + (b[2] - b[0]) * (b[3] - b[1]) - inter
+    return inter / union if union > 0 else 0.0
+
+
+class FixtureShapeTest(unittest.TestCase):
+    """The fixture is what the MobileDet graph emits: [1,100,4] [1,100] [1,100] [1]."""
+
+    def test_output_shapes(self) -> None:
+        for frame in (CATS, STREET):
+            out = frame["outputs"]
+            self.assertEqual(len(out["0"]), 1)
+            self.assertEqual(len(out["0"][0]), 100)
+            self.assertTrue(all(len(row) == 4 for row in out["0"][0]))
+            self.assertEqual(len(out["1"][0]), 100)
+            self.assertEqual(len(out["2"][0]), 100)
+            self.assertEqual(out["3"], [100.0])
+
+    def test_scores_are_sorted_descending(self) -> None:
+        # TFLite_Detection_PostProcess ranks by score; a reordered export would not.
+        scores = STREET["outputs"]["2"][0]
+        self.assertEqual(scores, sorted(scores, reverse=True))
+
+
+class OutputOrderTest(unittest.TestCase):
+    """Positional "1" is CLASSES and "2" is SCORES. Swapped, the labels are nonsense."""
+
+    def test_cats_decode_as_cats(self) -> None:
+        labels = [d["class"] for d in _decode(CATS)]
+        self.assertEqual(labels.count("cat"), 2, labels)
+
+    def test_street_decodes_three_people(self) -> None:
+        people = [d for d in _decode(STREET) if d["class"] == "person"]
+        self.assertEqual(len(people), 3)
+        # Left, middle and right of the frame.
+        centres = sorted((d["bbox"][0] + d["bbox"][2]) / 2 for d in people)
+        self.assertLess(centres[0], 200)
+        self.assertTrue(250 < centres[1] < 450, centres)
+        self.assertGreater(centres[2], 500)
+
+    def test_every_score_is_a_probability(self) -> None:
+        for frame in (CATS, STREET):
+            self.assertTrue(all(0.0 <= s <= 1.0 for s in frame["outputs"]["2"][0]))
+
+
+class ClassOffsetTest(unittest.TestCase):
+    """Emitted class index = COCO-90 line number of `coco_labels.txt`, 0 = person."""
+
+    def test_raw_indices_behind_the_labels(self) -> None:
+        classes = STREET["outputs"]["1"][0]
+        scores = STREET["outputs"]["2"][0]
+        top = [int(c) for c, s in zip(classes, scores) if s >= 0.7]
+        self.assertEqual(set(top), {0})  # the three people
+        cat_classes = {int(c) for c, s in zip(CATS["outputs"]["1"][0], CATS["outputs"]["2"][0]) if s >= 0.7}
+        self.assertEqual(cat_classes, {16})
+
+    def test_label_map(self) -> None:
+        self.assertEqual(len(COCO_90), 90)
+        self.assertEqual(label_for_class(0), "person")
+        self.assertEqual(label_for_class(2), "car")
+        self.assertEqual(label_for_class(16), "cat")
+        self.assertEqual(label_for_class(17), "dog")
+        self.assertEqual(label_for_class(89), "toothbrush")
+        self.assertEqual(label_for_class(11), "n/a")
+        self.assertEqual(label_for_class(90), "90")
+
+    def test_gap_classes_are_dropped(self) -> None:
+        out = {k: v for k, v in STREET["outputs"].items()}
+        out["1"] = [[11.0] + list(STREET["outputs"]["1"][0][1:])]  # "n/a" on the top row
+        labels = [d["class"] for d in _decode(STREET, outputs=out)]
+        self.assertNotIn("n/a", labels)
+        self.assertEqual(labels.count("person"), 2)
+
+
+class CountClampTest(unittest.TestCase):
+    """All 100 rows are read when count says 100, and only `count` rows otherwise."""
+
+    def test_low_threshold_reads_past_row_20(self) -> None:
+        # SSD MobileNet V2 stops at 20 rows; MobileDet's detections go on to row 100.
+        dets = _decode(STREET, confidence=0.01)
+        self.assertGreater(len(dets), 20)
+
+    def test_count_limits_the_rows(self) -> None:
+        out = dict(STREET["outputs"])
+        out["3"] = [2.0]
+        self.assertEqual(len(_decode(STREET, confidence=0.01, outputs=out)), 2)
+
+
+class LetterboxGeometryTest(unittest.TestCase):
+    """Boxes land in ORIGINAL-frame pixels, where another detector puts the same cats."""
+
+    # DETR ResNet-50 on this exact COCO frame (the facebook/detr-resnet-50 model
+    # card example): an independent reference for where the two cats are.
+    DETR_CATS = ([13.24, 52.05, 314.02, 470.93], [345.4, 23.85, 640.37, 368.72])
+
+    def test_cats_match_the_reference_boxes(self) -> None:
+        cats = [d["bbox"] for d in _decode(CATS) if d["class"] == "cat"]
+        for ref in self.DETR_CATS:
+            best = max(_iou(ref, box) for box in cats)
+            self.assertGreater(best, 0.85, (ref, cats))
+
+    def test_boxes_stay_inside_the_frame(self) -> None:
+        for frame in (CATS, STREET):
+            width, height = frame["orig"]
+            for d in _decode(frame, confidence=0.01):
+                x1, y1, x2, y2 = d["bbox"]
+                self.assertTrue(0 <= x1 < x2 <= width and 0 <= y1 < y2 <= height, d)
+
+
+class ScoreCeilingTest(unittest.TestCase):
+    """This graph cannot score above ~0.771, so a stricter threshold returns nothing."""
+
+    def test_no_score_exceeds_the_ceiling(self) -> None:
+        for frame in (CATS, STREET):
+            self.assertLessEqual(max(frame["outputs"]["2"][0]), SCORE_CEILING)
+
+    def test_the_ceiling_is_reached(self) -> None:
+        self.assertAlmostEqual(max(CATS["outputs"]["2"][0]), 0.76953125)
+
+    def test_threshold_above_the_ceiling_finds_nothing(self) -> None:
+        self.assertEqual(_decode(STREET, confidence=0.78), [])
+        self.assertEqual(len([d for d in _decode(STREET, confidence=0.65) if d["class"] == "person"]), 3)
+
+
+class NumpyInputTest(unittest.TestCase):
+    """The pool hands ndarrays; they must decode exactly like the lists above."""
+
+    @unittest.skipUnless(_HAS_REAL_NUMPY, "needs real numpy (not on CI's bare interpreter)")
+    def test_ndarrays_decode_like_lists(self) -> None:
+        np = _numpy_probe
+        for frame in (CATS, STREET):
+            arrays = {k: np.asarray(v, dtype=np.float32) for k, v in frame["outputs"].items()}
+            self.assertEqual(_decode(frame, confidence=0.3, outputs=arrays), _decode(frame, confidence=0.3))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/postprocessors/test_yunet.py

@@ -0,0 +1,292 @@
+"""Pins the YuNet decoder: prior layout, box/landmark decode, landmark order.
+
+YuNet out of the box found 0 faces on 413 person crops through the SCRFD
+decoder (2026-09-26 model-replacement spike, §2.2): one prior per cell instead
+of two, centre+exp(size) boxes instead of anchor distances, and a score split
+across `cls_*` and `obj_*`. Each class below pins one of those.
+
+`unittest.TestCase`, not pytest-style: `scripts/test-python-pool.sh` runs the
+`unittest.TestCase` modules on CI's bare interpreter — the self-hosted runner
+has NO numpy. So everything that decides is plain Python and tested here
+without it: prior layout, decode, landmark order, the score, NMS, the top-K cap,
+and the output gate (`check_outputs` runs before `postprocess_yunet` touches
+numpy, so its refusals are exercised through `postprocess_yunet` itself).
+
+What genuinely needs real numpy, and is SKIPPED (named) without it: the
+vectorised pre-filter (`np.maximum(cls, obj) >= conf`), and the decode of a
+live prior through `postprocess_yunet` end to end (flatten/reshape of the
+tensors, the cap applied inside it). Those run wherever numpy is installed —
+every pool host — and in the spike harness.
+"""
+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
+
+# `ndarray` is real-numpy-only: a stub another module installed would import.
+_HAS_REAL_NUMPY = _numpy_probe is not None and hasattr(_numpy_probe, "ndarray")
+
+# Without numpy, `yunet.py`'s `import numpy` is satisfied by an EMPTY stub for
+# the duration of the import only, and the stub is removed again at once: a
+# stub left in `sys.modules` would be picked up by the next test module in the
+# same `python3 -m unittest` process (test_scrfd needs `np.ceil` from its OWN
+# stub), making the result depend on module order. `yunet` keeps its own
+# reference; nothing it runs here touches it.
+if _numpy_probe is None:
+    sys.modules["numpy"] = types.ModuleType("numpy")
+    try:
+        import yunet  # noqa: F401
+    finally:
+        del sys.modules["numpy"]
+
+from yunet import (  # noqa: E402
+    NUM_LANDMARKS,
+    STRIDES,
+    TOP_K,
+    cap_top_k,
+    check_outputs,
+    decode_prior,
+    grid_cols,
+    missing_outputs,
+    nms,
+    postprocess_yunet,
+    prior_cell,
+    score_of,
+    to_source,
+    value_count,
+)
+
+
+class PriorLayoutTest(unittest.TestCase):
+    """One prior per cell, row-major — NOT SCRFD's two anchors per cell."""
+
+    def test_grid_is_one_prior_per_cell_at_640(self):
+        self.assertEqual([grid_cols(s, 640) for s in STRIDES], [80, 40, 20])
+        # 6400 + 1600 + 400. SCRFD's layout would be twice this (16800).
+        self.assertEqual(sum(grid_cols(s, 640) ** 2 for s in STRIDES), 8400)
+
+    def test_index_is_row_major(self):
+        cols = grid_cols(8, 640)
+        self.assertEqual(prior_cell(0, cols), (0, 0))
+        self.assertEqual(prior_cell(1, cols), (0, 1))  # SCRFD: index 1 is still cell (0,0)
+        self.assertEqual(prior_cell(cols + 2, cols), (1, 2))
+        self.assertEqual(prior_cell(cols * cols - 1, cols), (cols - 1, cols - 1))
+
+
+class DecodeTest(unittest.TestCase):
+    def test_box_is_centre_plus_exp_size_from_the_cell_corner(self):
+        # cell (row 1, col 2) at stride 8; centre offset (0.5, 0.5) → centre
+        # ((2+.5)*8, (1+.5)*8) = (20, 12); log size 0 → 8×8.
+        box, _ = decode_prior(8, 1, 2, [0.5, 0.5, 0.0, 0.0], [0.0] * 10)
+        self.assertEqual(box, (16.0, 8.0, 24.0, 16.0))
+
+    def test_size_is_exponential(self):
+        box, _ = decode_prior(16, 0, 0, [0.0, 0.0, math.log(3.0), math.log(2.0)], [0.0] * 10)
+        x1, y1, x2, y2 = box
+        self.assertAlmostEqual(x2 - x1, 48.0, places=4)  # 3 * 16
+        self.assertAlmostEqual(y2 - y1, 32.0, places=4)  # 2 * 16
+
+    def test_landmarks_are_cell_relative_in_stride_units(self):
+        kps = [0.25, 0.5, 0.75, 0.5, 0.5, 1.0, 0.25, 1.5, 0.75, 1.5]
+        _, points = decode_prior(32, 3, 4, [0.0, 0.0, 0.0, 0.0], kps)
+        self.assertEqual(len(points), NUM_LANDMARKS)
+        self.assertEqual(points[0], ((4 + 0.25) * 32, (3 + 0.5) * 32))
+        self.assertEqual(points[2], ((4 + 0.5) * 32, (3 + 1.0) * 32))
+
+    def test_score_is_geometric_mean_of_clamped_cls_and_obj(self):
+        self.assertAlmostEqual(score_of(0.81, 1.0), 0.9)
+        self.assertAlmostEqual(score_of(0.64, 0.25), 0.4)
+        self.assertEqual(score_of(1.3, 1.0), 1.0)
+        self.assertEqual(score_of(-0.2, 1.0), 0.0)
+
+    def test_to_source_undoes_the_letterbox(self):
+        # 320×160 crop letterboxed into 640: scale 2, pad (0, 160).
+        self.assertEqual(to_source(100.0, 260.0, 2.0, (0, 160)), (50.0, 50.0))
+
+
+class LandmarkOrderTest(unittest.TestCase):
+    """YuNet emits the SUBJECT's right eye first = image-LEFT eye, which is
+    the order `face-align.ts` maps onto ARCFACE_TEMPLATE_112. The decoder must
+    pass the five points through in model order — a sort or a swap here
+    mirrors every aligned face."""
+
+    def test_points_keep_model_order(self):
+        # A frontal face: image-left eye, image-right eye, nose, mouth L, mouth R.
+        kps = [0.2, 0.3, 0.8, 0.3, 0.5, 0.55, 0.3, 0.8, 0.7, 0.8]
+        _, points = decode_prior(8, 0, 0, [0.5, 0.5, 0.0, 0.0], kps)
+        xs = [p[0] for p in points]
+        self.assertLess(xs[0], xs[1])  # eye 0 is image-left
+        self.assertLess(xs[3], xs[4])  # mouth 3 is image-left
+        self.assertEqual([round(x, 3) for x in xs], [1.6, 6.4, 4.0, 2.4, 5.6])
+
+
+class MissingOutputsTest(unittest.TestCase):
+    """Name-only matching: a model without YuNet's twelve named tensors is
+    refused, not decoded as "no faces"."""
+
+    def test_all_twelve_present(self):
+        names = [f"{k}_{s}" for k in ("cls", "obj", "bbox", "kps") for s in STRIDES]
+        self.assertEqual(missing_outputs(names), [])
+
+    def test_names_what_is_missing(self):
+        names = [f"{k}_{s}" for k in ("cls", "bbox", "kps") for s in STRIDES]
+        self.assertEqual(missing_outputs(names), ["obj_8", "obj_16", "obj_32"])
+
+    def test_scrfd_style_outputs_are_refused(self):
+        names = [f"{k}_{s}" for k in ("score", "bbox", "kps") for s in STRIDES]
+        self.assertIn("cls_8", missing_outputs(names))
+
+
+def _list_outputs(input_size=640, drop=()):
+    """Correctly-SHAPED outputs as nested lists — no numpy needed."""
+    out = {}
+    for s in STRIDES:
+        n = grid_cols(s, input_size) ** 2
+        for kind, width in (("cls", 1), ("obj", 1), ("bbox", 4), ("kps", 10)):
+            if f"{kind}_{s}" not in drop:
+                out[f"{kind}_{s}"] = [[[0.0] * width for _ in range(n)]]
+    return out
+
+
+class OutputGateTest(unittest.TestCase):
+    """`check_outputs` runs before any numpy call, so these go through
+    `postprocess_yunet` itself on the bare interpreter."""
+
+    def test_missing_output_raises_instead_of_reporting_no_faces(self):
+        raw = _list_outputs(drop=("obj_32",))
+        with self.assertRaises(ValueError) as ctx:
+            postprocess_yunet(raw, {"confidence": 0.5}, 640, 640, 1.0, (0, 0))
+        self.assertIn("obj_32", str(ctx.exception))
+
+    def test_wrong_input_size_raises(self):
+        raw = _list_outputs(input_size=320)
+        with self.assertRaises(ValueError) as ctx:
+            postprocess_yunet(raw, {"confidence": 0.5, "inputSize": 640}, 640, 640, 1.0, (0, 0))
+        self.assertIn("does not match the model", str(ctx.exception))
+
+    def test_correct_outputs_pass_the_gate(self):
+        check_outputs(_list_outputs(), 640)  # no raise
+
+    def test_value_count_of_nested_lists(self):
+        self.assertEqual(value_count([[[0.0] * 4 for _ in range(3)]]), 12)
+        self.assertEqual(value_count(7.0), 1)
+
+
+class TopKCapTest(unittest.TestCase):
+    """The pure-Python NMS is O(n·kept): 5000 disjoint candidates took 2.8 s.
+    At most TOP_K, the best by score, may reach it."""
+
+    def _cands(self, n):
+        return [{"score": (i % 997) / 997.0, "_xyxy": (i, 0, i + 1, 1)} for i in range(n)]
+
+    def test_under_the_cap_is_untouched(self):
+        cands = self._cands(10)
+        kept, dropped = cap_top_k(cands)
+        self.assertIs(kept, cands)
+        self.assertEqual(dropped, 0)
+
+    def test_over_the_cap_keeps_the_best_k(self):
+        cands = self._cands(TOP_K + 250)
+        kept, dropped = cap_top_k(cands)
+        self.assertEqual(len(kept), TOP_K)
+        self.assertEqual(dropped, 250)
+        worst_kept = min(c["score"] for c in kept)
+        best_dropped = max(c["score"] for c in cands if c not in kept)
+        self.assertGreaterEqual(worst_kept, best_dropped)
+
+    def test_cap_is_well_below_upstream_and_above_real_frames(self):
+        # upstream 5000 (C++ NMS); measured max 110 candidates/frame at 0.1.
+        self.assertLessEqual(TOP_K, 5000)
+        self.assertGreaterEqual(TOP_K, 110 * 5)
+
+
+class NmsTest(unittest.TestCase):
+    def test_keeps_best_of_overlapping_and_disjoint(self):
+        cands = [
+            {"score": 0.6, "_xyxy": (0, 0, 10, 10)},
+            {"score": 0.9, "_xyxy": (1, 1, 11, 11)},
+            {"score": 0.7, "_xyxy": (50, 50, 60, 60)},
+        ]
+        kept = nms(cands, 0.45)
+        self.assertEqual([k["score"] for k in kept], [0.9, 0.7])
+
+
+def _outputs(np, input_size=640, live=None):
+    """Raw YuNet-shaped outputs, all priors dead except `live`:
+    {stride: (index, cls, obj, bbox4, kps10)}."""
+    out = {}
+    for s in STRIDES:
+        n = grid_cols(s, input_size) ** 2
+        out[f"cls_{s}"] = np.zeros((1, n, 1), np.float32)
+        out[f"obj_{s}"] = np.zeros((1, n, 1), np.float32)
+        out[f"bbox_{s}"] = np.zeros((1, n, 4), np.float32)
+        out[f"kps_{s}"] = np.zeros((1, n, 10), np.float32)
+    for s, (index, cls, obj, bbox, kps) in (live or {}).items():
+        out[f"cls_{s}"][0, index, 0] = cls
+        out[f"obj_{s}"][0, index, 0] = obj
+        out[f"bbox_{s}"][0, index] = bbox
+        out[f"kps_{s}"][0, index] = kps
+    return out
+
+
+@unittest.skipUnless(_HAS_REAL_NUMPY, "postprocess_yunet round trip needs real ndarray ops")
+class PostprocessYunetRoundTripTest(unittest.TestCase):
+    def setUp(self):
+        import numpy as np
+
+        self.np = np
+
+    def test_one_live_prior_decodes_to_source_pixels(self):
+        cols = grid_cols(16, 640)
+        index = 10 * cols + 20  # row 10, col 20
+        kps = [0.2, 0.3, 0.8, 0.3, 0.5, 0.55, 0.3, 0.8, 0.7, 0.8]
+        raw = _outputs(self.np, live={16: (index, 0.81, 1.0, [0.5, 0.5, math.log(4), math.log(4)], kps)})
+        # 1280×640 frame letterboxed into 640: scale 0.5, pad (0, 160).
+        out = postprocess_yunet(raw, {"confidence": 0.5, "inputSize": 640}, 1280, 640, 0.5, (0, 160))
+        dets = out["detections"]
+        self.assertEqual(len(dets), 1)
+        d = dets[0]
+        self.assertEqual(d["class"], "face")
+        self.assertAlmostEqual(d["score"], 0.9, places=3)
+        # network centre (328, 168), size 64 → [296,136,360,200] → source /0.5, y-160.
+        self.assertEqual(d["bbox"], [592.0, 0.0, 720.0, 80.0])
+        self.assertEqual(len(d["landmarks"]), NUM_LANDMARKS)
+        self.assertEqual(d["landmarks"][0], {"x": round((20.2 * 16) / 0.5, 1), "y": round((10.3 * 16 - 160) / 0.5, 1)})
+        self.assertLess(d["landmarks"][0]["x"], d["landmarks"][1]["x"])
+
+    def test_score_uses_both_tensors(self):
+        cols = grid_cols(8, 640)
+        # cls alone high, obj low → sqrt(0.9*0.1)=0.3 < 0.5: dropped.
+        raw = _outputs(self.np, live={8: (cols + 1, 0.9, 0.1, [0.5, 0.5, 1.0, 1.0], [0.0] * 10)})
+        out = postprocess_yunet(raw, {"confidence": 0.5}, 640, 640, 1.0, (0, 0))
+        self.assertEqual(out["detections"], [])
+
+    def test_prior_with_low_cls_but_high_obj_still_passes(self):
+        # sqrt(0.45 * 0.95) = 0.654 >= 0.5 although cls alone is under it: a
+        # prefilter on ONE tensor would drop a real face here.
+        cols = grid_cols(32, 640)
+        raw = _outputs(self.np, live={32: (cols + 3, 0.45, 0.95, [0.5, 0.5, 0.0, 0.0], [0.0] * 10)})
+        out = postprocess_yunet(raw, {"confidence": 0.5}, 640, 640, 1.0, (0, 0))
+        self.assertEqual(len(out["detections"]), 1)
+        self.assertAlmostEqual(out["detections"][0]["score"], 0.6538, places=3)
+
+    def test_cap_applies_inside_postprocess(self):
+        # TOP_K + 50 disjoint live priors on the stride-8 grid: all pass the
+        # score gate, none overlap, so only the cap can remove any.
+        n = grid_cols(8, 640) ** 2
+        raw = _outputs(self.np)
+        live = list(range(0, n, 2))[: TOP_K + 50]
+        raw["cls_8"][0, live, 0] = 0.9
+        raw["obj_8"][0, live, 0] = 0.9
+        raw["bbox_8"][0, live] = [0.5, 0.5, -1.0, -1.0]  # ~3 px boxes, disjoint
+        out = postprocess_yunet(raw, {"confidence": 0.5}, 640, 640, 1.0, (0, 0))
+        self.assertEqual(len(out["detections"]), TOP_K)
+
+
+if __name__ == "__main__":
+    unittest.main()