feat: add CompactMask for memory-efficient crop-RLE mask storage

Dense (N, H, W) bool masks cause OOM for aerial imagery (1000 objects x
4K image ~ 8.3 GB). CompactMask encodes each mask as a run-length
sequence of its bounding-box crop, reducing typical usage to ~2 MB.

- New `CompactMask` class with full duck-typed ndarray interface:
  `__getitem__`, `__array__`, `shape`, `dtype`, `area`, `sum`, `merge`,
  `with_offset` — drop-in compatible with existing `np.ndarray` masks.
- Private row-major RLE helpers: `_rle_encode`, `_rle_decode`, `_rle_area`.
- Phase 2 integration: `Detections` accepts CompactMask for `mask` field;
  `validate_mask`, `area` property, and `Detections.merge` all handle it.
- Phase 3 optimised paths: `calculate_masks_centroids` uses crop-space
  arithmetic; `MaskAnnotator` paints crop regions directly; `move_detections`
  uses `with_offset` instead of materialising dense masks; `get_mask_size_category`
  uses `mask.area`.
- 54 new tests (41 unit + 13 integration); all 17 doctests pass.
- All 1190 existing tests pass; pre-commit hooks clean.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Borda

src/supervision/__init__.py

@@ -45,6 +45,7 @@
 )
 from supervision.dataset.formats.coco import get_coco_class_index_mapping
 from supervision.dataset.utils import mask_to_rle, rle_to_mask
+from supervision.detection.compact_mask import CompactMask
 from supervision.detection.core import Detections
 from supervision.detection.line_zone import (
     LineZone,

src/supervision/annotators/core.py

@@ -2,7 +2,7 @@
 
 from functools import lru_cache
 from math import sqrt
-from typing import Any, overload
+from typing import Any, cast, overload
 
 import cv2
 import numpy as np
@@ -434,6 +434,13 @@ def annotate(
 
         colored_mask = np.array(scene, copy=True, dtype=np.uint8)
 
+        from supervision.detection.compact_mask import CompactMask
+
+        compact_mask = (
+            cast(CompactMask, detections.mask)
+            if isinstance(detections.mask, CompactMask)
+            else None
+        )
         for detection_idx in np.flip(np.argsort(detections.area)):
             color = resolve_color(
                 color=self.color,
@@ -443,8 +450,22 @@ def annotate(
                 if custom_color_lookup is None
                 else custom_color_lookup,
             )
-            mask = np.asarray(detections.mask[detection_idx], dtype=bool)
-            colored_mask[mask] = color.as_bgr()
+            if compact_mask is not None:
+                # Paint only the bounding-box crop — avoids a full (H, W) alloc.
+                x1 = int(compact_mask._offsets[detection_idx, 0])
+                y1 = int(compact_mask._offsets[detection_idx, 1])
+                crop_h = int(compact_mask._crop_shapes[detection_idx, 0])
+                crop_w = int(compact_mask._crop_shapes[detection_idx, 1])
+                crop_m = compact_mask.crop(detection_idx)
+                colored_mask[y1 : y1 + crop_h, x1 : x1 + crop_w][crop_m] = (
+                    color.as_bgr()
+                )
+            else:
+                mask = np.asarray(
+                    detections.mask[detection_idx],
+                    dtype=bool,
+                )
+                colored_mask[mask] = color.as_bgr()
 
         cv2.addWeighted(
             colored_mask, self.opacity, scene, 1 - self.opacity, 0, dst=scene