perf(detection): vectorize box_iou_batch_with_jaccard

`box_iou_batch_with_jaccard` computed COCO-style Jaccard IoU with a double
Python `for` loop calling a scalar `_jaccard` helper once per (detection,
ground-truth) pair — an O(N*M) per-element pattern in otherwise pure-NumPy
code. It is the inner IoU of `COCOEvaluator._compute_iou`, called once per
(image, category) during mAP evaluation, and is also public API
(`sv.box_iou_batch_with_jaccard`).

Replace the loop with a broadcasted NumPy implementation and drop the now
unused scalar `_jaccard`. The far corners are built as `x2 = x + w` and the
union is associated as `(area_det + area_gt - area_inter) + eps` so the
result is bit-identical to the previous per-pair output (verified to
`max|diff| = 0` over 4000 randomized trials including zero/negative-width
degenerate boxes and crowd flags). Crowd semantics are preserved: a crowd
ground truth uses the detection area as the union.

Speedup scales with batch size — ~1.6x at 5x5, ~27x at 15x60, ~66x at
50x100 — and is faster even at the smallest sizes, so there is no regime
where it regresses. End-to-end COCO mAP results are unchanged (the existing
metrics suite passes without modification).

Adds `TestBoxIouBatchWithJaccard`: parity against an independent per-pair
reference across empty / single / busy / degenerate+crowd batches, the crowd
union semantics, the empty-input contract, and the `is_crowd` length guard.

Author: RubenHaisma

src/supervision/detection/utils/iou_and_nms.py

@@ -261,46 +261,6 @@ def box_iou_batch(
     return out
 
 
-def _jaccard(box_a: list[float], box_b: list[float], is_crowd: bool) -> float:
-    """
-    Calculate the Jaccard index (intersection over union) between two bounding boxes.
-    If a gt object is marked as "iscrowd", a dt is allowed to match any subregion
-    of the gt. Choosing gt'=intersect(dt,gt). Since by definition union(gt',dt)=dt, computing
-    iou(gt,dt,iscrowd) = iou(gt',dt) = area(intersect(gt,dt)) / area(dt)
-
-    Args:
-        box_a: Box coordinates in the format [x, y, width, height].
-        box_b: Box coordinates in the format [x, y, width, height].
-        iscrowd: Flag indicating if the second box is a crowd region or not.
-
-    Returns:
-        Jaccard index between the two bounding boxes.
-    """  # noqa: E501
-    # Smallest number to avoid division by zero
-    EPS = np.spacing(1)
-
-    xa, ya, x2a, y2a = box_a[0], box_a[1], box_a[0] + box_a[2], box_a[1] + box_a[3]
-    xb, yb, x2b, y2b = box_b[0], box_b[1], box_b[0] + box_b[2], box_b[1] + box_b[3]
-
-    # Innermost left x
-    xi = max(xa, xb)
-    # Innermost right x
-    x2i = min(x2a, x2b)
-    # Same for y
-    yi = max(ya, yb)
-    y2i = min(y2a, y2b)
-
-    # Calculate areas
-    Aa = max(x2a - xa, 0.0) * max(y2a - ya, 0.0)
-    Ab = max(x2b - xb, 0.0) * max(y2b - yb, 0.0)
-    Ai = max(x2i - xi, 0.0) * max(y2i - yi, 0.0)
-
-    if is_crowd:
-        return float(Ai / (Aa + EPS))
-
-    return float(Ai / (Aa + Ab - Ai + EPS))
-
-
 def box_iou_batch_with_jaccard(
     boxes_true: list[list[float]],
     boxes_detection: list[list[float]],
@@ -351,13 +311,39 @@ def box_iou_batch_with_jaccard(
     )
     if len(boxes_detection) == 0 or len(boxes_true) == 0:
         return cast(npt.NDArray[np.float64], np.array([]))
-    ious: npt.NDArray[np.float64] = np.zeros(
-        (len(boxes_detection), len(boxes_true)), dtype=np.float64
+
+    # Smallest number to avoid division by zero.
+    eps = np.spacing(1)
+    gt = np.asarray(boxes_true, dtype=np.float64)
+    dt = np.asarray(boxes_detection, dtype=np.float64)
+    crowd = np.asarray(is_crowd, dtype=bool)
+
+    # Boxes are [x, y, w, h]. Build the far corners as `x2 = x + w` (rather than
+    # reusing `w`) so that the area/intersection arithmetic is bit-identical to
+    # the per-pair reference it replaces.
+    gt_x2, gt_y2 = gt[:, 0] + gt[:, 2], gt[:, 1] + gt[:, 3]
+    dt_x2, dt_y2 = dt[:, 0] + dt[:, 2], dt[:, 1] + dt[:, 3]
+
+    # Pairwise intersection: rows index detections, columns index ground truth.
+    inter_x1 = np.maximum(dt[:, 0][:, None], gt[:, 0][None, :])
+    inter_y1 = np.maximum(dt[:, 1][:, None], gt[:, 1][None, :])
+    inter_x2 = np.minimum(dt_x2[:, None], gt_x2[None, :])
+    inter_y2 = np.minimum(dt_y2[:, None], gt_y2[None, :])
+    area_inter = np.maximum(inter_x2 - inter_x1, 0.0) * np.maximum(
+        inter_y2 - inter_y1, 0.0
+    )
+
+    area_det = np.maximum(dt_x2 - dt[:, 0], 0.0) * np.maximum(dt_y2 - dt[:, 1], 0.0)
+    area_gt = np.maximum(gt_x2 - gt[:, 0], 0.0) * np.maximum(gt_y2 - gt[:, 1], 0.0)
+
+    # For a crowd ground truth a detection may match any subregion, so its union
+    # collapses to the detection area; otherwise use the standard box union.
+    area_norm = np.where(
+        crowd[None, :],
+        area_det[:, None] + eps,
+        area_det[:, None] + area_gt[None, :] - area_inter + eps,
     )
-    for gt_idx, gt_box in enumerate(boxes_true):
-        for det_idx, det_box in enumerate(boxes_detection):
-            ious[det_idx, gt_idx] = _jaccard(det_box, gt_box, is_crowd[gt_idx])
-    return ious
+    return cast(npt.NDArray[np.float64], area_inter / area_norm)
 
 
 def _polygon_areas(polygons: npt.NDArray[np.floating]) -> npt.NDArray[np.floating]:

tests/detection/utils/test_iou_and_nms.py

@@ -10,6 +10,7 @@
     _group_overlapping_boxes,
     box_iou,
     box_iou_batch,
+    box_iou_batch_with_jaccard,
     box_non_max_suppression,
     mask_iou_batch,
     mask_non_max_merge,
@@ -1739,3 +1740,87 @@ def test_detection_exceeds_limit_warns_and_completes(self) -> None:
         with pytest.warns(UserWarning, match="exceed"):
             result = mask_iou_batch(masks_true, masks_detection, memory_limit=1)
         assert result.shape == (3, 500)
+
+
+def _reference_jaccard_loop(
+    boxes_true: list[list[float]],
+    boxes_detection: list[list[float]],
+    is_crowd: list[bool],
+) -> np.ndarray:
+    """Independent per-pair COCO Jaccard reference, shape (len(dt), len(gt))."""
+    eps = np.spacing(1)
+    out = np.zeros((len(boxes_detection), len(boxes_true)), dtype=np.float64)
+    for gt_idx, (gx, gy, gw, gh) in enumerate(boxes_true):
+        for dt_idx, (dx, dy, dw, dh) in enumerate(boxes_detection):
+            inter_w = max(min(dx + dw, gx + gw) - max(dx, gx), 0.0)
+            inter_h = max(min(dy + dh, gy + gh) - max(dy, gy), 0.0)
+            area_inter = inter_w * inter_h
+            area_det = max(dw, 0.0) * max(dh, 0.0)
+            area_gt = max(gw, 0.0) * max(gh, 0.0)
+            if is_crowd[gt_idx]:
+                out[dt_idx, gt_idx] = area_inter / (area_det + eps)
+            else:
+                out[dt_idx, gt_idx] = area_inter / (
+                    area_det + area_gt - area_inter + eps
+                )
+    return out
+
+
+class TestBoxIouBatchWithJaccard:
+    """Verify the vectorized COCO-style Jaccard IoU batch."""
+
+    @pytest.mark.parametrize(
+        ("n_gt", "n_dt", "seed"),
+        [
+            pytest.param(1, 1, 1, id="single-pair"),
+            pytest.param(3, 5, 2, id="small-batch"),
+            pytest.param(20, 50, 3, id="busy-batch"),
+            pytest.param(8, 8, 4, id="degenerate-and-crowd"),
+        ],
+    )
+    def test_matches_per_pair_reference(self, n_gt: int, n_dt: int, seed: int) -> None:
+        """Vectorized output equals an independent per-pair Jaccard loop."""
+        rng = np.random.default_rng(seed)
+
+        def _boxes(n: int) -> list[list[float]]:
+            xy = rng.uniform(0, 100, (n, 2))
+            wh = rng.uniform(0, 40, (n, 2))
+            if seed == 4 and n:  # inject zero/negative-width degenerate boxes
+                wh[rng.integers(0, n), 0] = rng.choice([0.0, -5.0])
+            return np.hstack([xy, wh]).tolist()
+
+        boxes_true, boxes_detection = _boxes(n_gt), _boxes(n_dt)
+        is_crowd = (rng.random(n_gt) < 0.3).tolist()
+
+        result = box_iou_batch_with_jaccard(boxes_true, boxes_detection, is_crowd)
+        expected = _reference_jaccard_loop(boxes_true, boxes_detection, is_crowd)
+
+        assert result.shape == (n_dt, n_gt)
+        np.testing.assert_allclose(result, expected, atol=1e-12)
+
+    def test_crowd_uses_detection_area_as_union(self) -> None:
+        """A crowd gt enclosing the detection scores 1.0 (union == detection area)."""
+        boxes_true = [[0.0, 0.0, 100.0, 100.0]]
+        boxes_detection = [[10.0, 10.0, 20.0, 20.0]]  # fully inside the gt
+        crowd = box_iou_batch_with_jaccard(boxes_true, boxes_detection, [True])
+        non_crowd = box_iou_batch_with_jaccard(boxes_true, boxes_detection, [False])
+        assert crowd[0, 0] == pytest.approx(1.0)
+        assert non_crowd[0, 0] == pytest.approx(0.04)  # 400 / 10000
+
+    @pytest.mark.parametrize(
+        ("n_gt", "n_dt"),
+        [pytest.param(0, 3, id="empty-gt"), pytest.param(3, 0, id="empty-dt")],
+    )
+    def test_empty_input_returns_empty_array(self, n_gt: int, n_dt: int) -> None:
+        """Empty gt or detections yields an empty array, preserving the contract."""
+        boxes_true = [[0.0, 0.0, 10.0, 10.0]] * n_gt
+        boxes_detection = [[0.0, 0.0, 10.0, 10.0]] * n_dt
+        result = box_iou_batch_with_jaccard(boxes_true, boxes_detection, [False] * n_gt)
+        assert result.size == 0
+
+    def test_mismatched_is_crowd_length_raises(self) -> None:
+        """`is_crowd` must align with `boxes_true`."""
+        with pytest.raises(AssertionError):
+            box_iou_batch_with_jaccard(
+                [[0.0, 0.0, 1.0, 1.0]], [[0.0, 0.0, 1.0, 1.0]], []
+            )