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

examples/time_in_zone/README.md

@@ -222,7 +222,7 @@ Script to run object detection on an RTSP stream using the RF-DETR model.
 - `--model_size`: RF-DETR backbone size to load — choose from 'nano', 'small', 'medium', 'base', or 'large' (default 'medium').
 - `--device`: Compute device to run the model on ('cpu', 'mps', or 'cuda'; default 'cpu').
 - `--classes`: Space-separated list of class IDs to track. Leave empty to track all classes.
-- `--confidence_threshold`: Minimum confidence score for a detection to be kept, range 0–1 (default 0.3).
+- `--confidence_threshold`: Minimum confidence score for a detection to be kept, range 0-1 (default 0.3).
 - `--iou_threshold`: IOU threshold applied during non-max suppression (default 0.7).
 - `--resolution`: Shortest-side input resolution supplied to the model. The script will round it to the nearest valid multiple (default 640).
 

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,
@@ -161,6 +162,7 @@
     "ColorAnnotator",
     "ColorLookup",
     "ColorPalette",
+    "CompactMask",
     "ComparisonAnnotator",
     "ConfusionMatrix",
     "CropAnnotator",

src/supervision/annotators/core.py

@@ -434,6 +434,11 @@ def annotate(
 
         colored_mask = np.array(scene, copy=True, dtype=np.uint8)
 
+        from supervision.detection.compact_mask import CompactMask
+
+        compact_mask = (
+            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 +448,21 @@ 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_m = compact_mask.crop(detection_idx)
+                crop_h, crop_w = crop_m.shape
+                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
@@ -2900,8 +2918,8 @@ def annotate(self, scene: ImageType, detections: Detections) -> ImageType:
                 colored_mask[y1:y2, x1:x2] = scene[y1:y2, x1:x2]
         else:
             for mask in detections.mask:
-                mask = np.asarray(mask, dtype=bool)
-                colored_mask[mask] = scene[mask]
+                mask_bool = np.asarray(mask, dtype=bool)
+                colored_mask[mask_bool] = scene[mask_bool]
 
         np.copyto(scene, colored_mask)
         return scene