feat(utils): add TkImageWindow to unblock switch to opencv-python-headless

docs/changelog.md

@@ -47,6 +47,11 @@ date_modified: 2026-07-08
 - Fixed: dataset IO/export edge cases now avoid mutating caller-owned `Detections` during `DetectionDataset` construction, reject non-integer and out-of-range class ids with a clear `ValueError`, load COCO annotations that omit optional `iscrowd`/`area` fields, expose `DetectionDataset.from_coco(use_iscrowd=...)` without changing the existing positional `show_progress` argument, export mask pixel area to COCO when no stored area is present, ignore folder-structure root clutter and non-image files inside class folders, and accept PIL-readable YOLO images such as RGBA or palette PNGs.
 
 ### Added
+- Added: [`sv.ImageWindow`](utils/image_window.md/#supervision.utils.image_window.ImageWindow) — tkinter + Pillow desktop window that replaces `cv2.imshow` / `cv2.waitKey`, usable regardless of which OpenCV wheel (or none) is installed. Key differences from cv2:
+  - `wait_key()` returns a tkinter keysym `str` (e.g. `"q"`, `"Escape"`) or `None`, not an `int` — update `key == ord("q")` to `key == "q"`.
+  - Mouse callback signature is `(x: int, y: int, event_type: str)` where `event_type` is `"down"`, `"up"`, or `"move"` — incompatible with cv2's `(event, x, y, flags, param)`.
+  - Only left-button events are captured; scroll, right-button, and modifier flags have no equivalent.
+  - Requires `python3-tk` (not pip-installable): `sudo apt-get install python3-tk` on Debian/Ubuntu, `brew install tcl-tk` on macOS with Homebrew/pyenv.
 - `KeyPoints.merge` — combine a list of `KeyPoints` objects into one, mirroring `Detections.merge`. Empty inputs are ignored; all non-empty inputs must share the same number of keypoints per skeleton. Completes the merge-then-suppress workflow introduced by `KeyPoints.with_nms` ([#2412](https://github.com/roboflow/supervision/pull/2412))
 - `BaseAnnotator.requires_mask` — class-level `bool` flag on all annotators; `True` for `MaskAnnotator`, `PolygonAnnotator`, and `HaloAnnotator`; `False` for all others. Integrations can inspect this before materializing expensive mask payloads ([#2370](https://github.com/roboflow/supervision/pull/2370))
 - `CompactMask.from_coco_rle` — efficient COCO RLE ingestion into crop-scoped compact mask format without materializing dense `(N, H, W)` arrays ([#2367](https://github.com/roboflow/supervision/pull/2367))

docs/faq.md

@@ -53,6 +53,27 @@ Install `supervision[metrics]`, then use `supervision.metrics.mean_average_preci
 
 Yes. Supervision is free and open source under the MIT license.
 
+## How do I process frames from a webcam with supervision?
+
+Supervision does not support live camera capture. Manage the capture device yourself with `cv2.VideoCapture`, which works regardless of which OpenCV wheel (`opencv-python` or `opencv-python-headless`) is installed, and pass individual frames to supervision annotators:
+
+```python
+import cv2  # requires: pip install opencv-python (or opencv-python-headless)
+import supervision as sv
+
+cap = cv2.VideoCapture(0)
+annotator = sv.BoxAnnotator()
+
+while True:
+    ret, frame = cap.read()
+    if not ret:
+        break
+    # run your detector, then annotate:
+    # annotated = annotator.annotate(frame, detections)
+
+cap.release()
+```
+
 ## Where is the source code?
 
 The source code is available at [github.com/roboflow/supervision](https://github.com/roboflow/supervision).

docs/utils/image_window.md

@@ -0,0 +1,12 @@
+---
+comments: true
+status: new
+---
+
+# Image Window
+
+<div class="md-typeset">
+    <h2><a href="#supervision.utils.image_window.ImageWindow">ImageWindow</a></h2>
+</div>
+
+:::supervision.utils.image_window.ImageWindow

examples/count_people_in_zone/inference_example.py

@@ -1,7 +1,6 @@
 import json
 import os
 
-import cv2
 import numpy as np
 from inference.core.models.roboflow import RoboflowInferenceModel
 from inference.models.utils import get_roboflow_model
@@ -117,7 +116,7 @@ def annotate(
     """
     annotated_frame = frame.copy()
     for zone, zone_annotator, box_annotator in zip(
-        zones, zone_annotators, box_annotators
+        zones, zone_annotators, box_annotators, strict=True
     ):
         detections_in_zone = detections[zone.trigger(detections=detections)]
         annotated_frame = zone_annotator.annotate(scene=annotated_frame)
@@ -179,6 +178,7 @@ def main(
                 )
                 sink.write_frame(annotated_frame)
     else:
+        window = sv.ImageWindow("Processed Video")
         for frame in tqdm(frames_generator, total=video_info.total_frames):
             detections = detect(frame, model, confidence_threshold, iou_threshold)
             annotated_frame = annotate(
@@ -188,11 +188,12 @@ def main(
                 box_annotators=box_annotators,
                 detections=detections,
             )
-            cv2.imshow("Processed Video", annotated_frame)
-            if cv2.waitKey(1) & 0xFF == ord("q"):
+            window.show(annotated_frame)
+            key = window.wait_key(1)
+            if not window.is_open or key == "q":
                 break
 
-        cv2.destroyAllWindows()
+        window.close()
 
 
 if __name__ == "__main__":

examples/count_people_in_zone/ultralytics_example.py

@@ -1,6 +1,5 @@
 import json
 
-import cv2
 import numpy as np
 from tqdm import tqdm
 from ultralytics import YOLO
@@ -116,7 +115,7 @@ def annotate(
     """
     annotated_frame = frame.copy()
     for zone, zone_annotator, box_annotator in zip(
-        zones, zone_annotators, box_annotators
+        zones, zone_annotators, box_annotators, strict=True
     ):
         detections_in_zone = detections[zone.trigger(detections=detections)]
         annotated_frame = zone_annotator.annotate(scene=annotated_frame)
@@ -167,6 +166,7 @@ def main(
                 )
                 sink.write_frame(annotated_frame)
     else:
+        window = sv.ImageWindow("Processed Video")
         for frame in tqdm(frames_generator, total=video_info.total_frames):
             detections = detect(frame, model, confidence_threshold, iou_threshold)
             annotated_frame = annotate(
@@ -176,11 +176,12 @@ def main(
                 box_annotators=box_annotators,
                 detections=detections,
             )
-            cv2.imshow("Processed Video", annotated_frame)
-            if cv2.waitKey(1) & 0xFF == ord("q"):
+            window.show(annotated_frame)
+            key = window.wait_key(1)
+            if not window.is_open or key == "q":
                 break
 
-        cv2.destroyAllWindows()
+        window.close()
 
 
 if __name__ == "__main__":

examples/speed_estimation/inference_example.py

@@ -96,6 +96,7 @@ def main(
     coordinates = defaultdict(lambda: deque(maxlen=int(video_info.fps)))
 
     with sv.VideoSink(target_video_path, video_info) as sink:
+        window = sv.ImageWindow("frame")
         for frame in frame_generator:
             results = model.infer(
                 frame, confidence=confidence_threshold, iou=iou_threshold
@@ -109,7 +110,7 @@ def main(
             )
             points = view_transformer.transform_points(points=points).astype(int)
 
-            for tracker_id, [_, y] in zip(detections.tracker_id, points):
+            for tracker_id, [_, y] in zip(detections.tracker_id, points, strict=True):
                 coordinates[tracker_id].append(y)
 
             labels = []
@@ -136,10 +137,11 @@ def main(
             )
 
             sink.write_frame(annotated_frame)
-            cv2.imshow("frame", annotated_frame)
-            if cv2.waitKey(1) & 0xFF == ord("q"):
+            window.show(annotated_frame)
+            key = window.wait_key(1)
+            if not window.is_open or key == "q":
                 break
-        cv2.destroyAllWindows()
+        window.close()
 
 
 if __name__ == "__main__":

examples/speed_estimation/ultralytics_example.py

@@ -82,6 +82,7 @@ def main(
     coordinates = defaultdict(lambda: deque(maxlen=int(video_info.fps)))
 
     with sv.VideoSink(target_video_path, video_info) as sink:
+        window = sv.ImageWindow("frame")
         for frame in frame_generator:
             result = model(frame, conf=confidence_threshold, iou=iou_threshold)[0]
             detections = sv.Detections.from_ultralytics(result)
@@ -93,7 +94,7 @@ def main(
             )
             points = view_transformer.transform_points(points=points).astype(int)
 
-            for tracker_id, [_, y] in zip(detections.tracker_id, points):
+            for tracker_id, [_, y] in zip(detections.tracker_id, points, strict=True):
                 coordinates[tracker_id].append(y)
 
             labels = []
@@ -120,10 +121,11 @@ def main(
             )
 
             sink.write_frame(annotated_frame)
-            cv2.imshow("frame", annotated_frame)
-            if cv2.waitKey(1) & 0xFF == ord("q"):
+            window.show(annotated_frame)
+            key = window.wait_key(1)
+            if not window.is_open or key == "q":
                 break
-        cv2.destroyAllWindows()
+        window.close()
 
 
 if __name__ == "__main__":

examples/speed_estimation/yolo_nas_example.py

@@ -83,6 +83,7 @@ def main(
     coordinates = defaultdict(lambda: deque(maxlen=int(video_info.fps)))
 
     with sv.VideoSink(target_video_path, video_info) as sink:
+        window = sv.ImageWindow("frame")
         for frame in frame_generator:
             result = model.predict(frame, conf=confidence_threshold, iou=iou_threshold)[
                 0
@@ -123,10 +124,11 @@ def main(
             )
 
             sink.write_frame(annotated_frame)
-            cv2.imshow("frame", annotated_frame)
-            if cv2.waitKey(1) & 0xFF == ord("q"):
+            window.show(annotated_frame)
+            key = window.wait_key(1)
+            if not window.is_open or key == "q":
                 break
-        cv2.destroyAllWindows()
+        window.close()
 
 
 if __name__ == "__main__":

examples/time_in_zone/README.md

@@ -30,6 +30,8 @@ https://github.com/roboflow/supervision/assets/26109316/d051cc8a-dd15-41d4-aa36-
     uv pip install -r requirements.txt
     ```
 
+The three RTSP `*_stream_example.py` scripts display frames from an `InferencePipeline` callback running on a worker thread, so they use OpenCV HighGUI instead of `sv.ImageWindow`. Install `opencv-python` and keep only one OpenCV wheel installed to run those scripts. The file and naive-stream examples use `sv.ImageWindow`, which works regardless of which OpenCV wheel (or none) is installed.
+
 ## 🛠 scripts
 
 ### `download_from_youtube`

examples/time_in_zone/inference_file_example.py

@@ -1,4 +1,3 @@
-import cv2
 import numpy as np
 from inference import get_model
 from utils.general import find_in_list, load_zones_config
@@ -49,6 +48,7 @@ def main(
     ]
     timers = [FPSBasedTimer(video_info.fps) for _ in zones]
 
+    window = sv.ImageWindow("Processed Video")
     for frame in frames_generator:
         results = model.infer(
             frame, confidence=confidence_threshold, iou_threshold=iou_threshold
@@ -84,10 +84,11 @@ def main(
                 custom_color_lookup=custom_color_lookup,
             )
 
-        cv2.imshow("Processed Video", annotated_frame)
-        if cv2.waitKey(1) & 0xFF == ord("q"):
+        window.show(annotated_frame)
+        key = window.wait_key(1)
+        if not window.is_open or key == "q":
             break
-    cv2.destroyAllWindows()
+    window.close()
 
 
 if __name__ == "__main__":

examples/time_in_zone/inference_naive_stream_example.py

@@ -1,4 +1,3 @@
-import cv2
 import numpy as np
 from inference import get_model
 from utils.general import find_in_list, get_stream_frames_generator, load_zones_config
@@ -49,6 +48,7 @@ def main(
     ]
     timers = [ClockBasedTimer() for _ in zones]
 
+    window = sv.ImageWindow("Processed Video")
     for frame in frames_generator:
         fps_monitor.tick()
         fps = fps_monitor.fps
@@ -94,10 +94,11 @@ def main(
                 custom_color_lookup=custom_color_lookup,
             )
 
-        cv2.imshow("Processed Video", annotated_frame)
-        if cv2.waitKey(1) & 0xFF == ord("q"):
+        window.show(annotated_frame)
+        key = window.wait_key(1)
+        if not window.is_open or key == "q":
             break
-    cv2.destroyAllWindows()
+    window.close()
 
 
 if __name__ == "__main__":

examples/time_in_zone/rfdetr_file_example.py

@@ -2,7 +2,6 @@
 
 from enum import Enum
 
-import cv2
 import numpy as np
 from rfdetr import RFDETRBase, RFDETRLarge, RFDETRMedium, RFDETRNano, RFDETRSmall
 from utils.general import find_in_list, load_zones_config
@@ -128,6 +127,7 @@ def main(
     ]
     timers = [FPSBasedTimer(video_info.fps) for _ in zones]
 
+    window = sv.ImageWindow("Processed Video")
     for frame in frames_generator:
         detections = model.predict(frame, threshold=confidence_threshold)
         detections = detections[find_in_list(detections.class_id, classes)]
@@ -161,10 +161,11 @@ def main(
                 custom_color_lookup=custom_color_lookup,
             )
 
-        cv2.imshow("Processed Video", annotated_frame)
-        if cv2.waitKey(1) & 0xFF == ord("q"):
+        window.show(annotated_frame)
+        key = window.wait_key(1)
+        if not window.is_open or key == "q":
             break
-    cv2.destroyAllWindows()
+    window.close()
 
 
 if __name__ == "__main__":

examples/time_in_zone/rfdetr_naive_stream_example.py

@@ -2,7 +2,6 @@
 
 from enum import Enum
 
-import cv2
 import numpy as np
 from rfdetr import RFDETRBase, RFDETRLarge, RFDETRMedium, RFDETRNano, RFDETRSmall
 from utils.general import find_in_list, get_stream_frames_generator, load_zones_config
@@ -128,6 +127,7 @@ def main(
     ]
     timers = [ClockBasedTimer() for _ in zones]
 
+    window = sv.ImageWindow("Processed Video")
     for frame in frames_generator:
         fps_monitor.tick()
         fps = fps_monitor.fps
@@ -171,11 +171,12 @@ def main(
                 custom_color_lookup=custom_color_lookup,
             )
 
-        cv2.imshow("Processed Video", annotated_frame)
-        if cv2.waitKey(1) & 0xFF == ord("q"):
+        window.show(annotated_frame)
+        key = window.wait_key(1)
+        if not window.is_open or key == "q":
             break
 
-    cv2.destroyAllWindows()
+    window.close()
 
 
 if __name__ == "__main__":