supervision

Warnings

• breaking Python 3.8 support was dropped in version 0.26.0. Users on older Python versions must upgrade to Python 3.9 or newer.
  Fix: Upgrade your Python environment to 3.9 or higher. `supervision` also supports Python 3.13+.
• gotcha The `sv.MeanAveragePrecision` metric had a bug prior to version 0.26.1 where the area used for size-specific evaluation (small/medium/large) was always zero unless explicitly provided. This could lead to incorrect mAP results for those specific categories.
  Fix: Upgrade to `supervision==0.26.1` or newer to ensure correct `MeanAveragePrecision` calculations, especially for size-specific evaluations.
• gotcha The `LineZone` and related components received significant updates in version 0.25.0. While enhancing robustness, existing implementations of line-zone counting might experience behavioral changes or require minor adjustments, especially concerning edge cases or specific crossing logic.
  Fix: Review existing `LineZone` implementations after upgrading to 0.25.0+ to ensure continued correct behavior. Refer to the official documentation for the latest usage patterns.
• gotcha Many core functionalities (e.g., annotators, image processing utilities) within `supervision` rely on `opencv-python` and `numpy`. While `supervision` can be installed without these as strict dependencies, attempting to use these features without them will result in `ImportError` or other runtime errors.
  Fix: Ensure `opencv-python` and `numpy` are installed (`pip install opencv-python numpy`) if you plan to use any image annotation or processing features. Alternatively, `pip install supervision[all]` will include these.

Install

• pip install supervision Core library
• pip install supervision[all] With all optional dependencies (e.g., for YOLO, OCR, SAM)

Imports

• supervision as sv

  import supervision as sv

  The canonical way to import and use the library, accessing classes like sv.Detections, sv.BoxAnnotator, etc.
• Detections

  import supervision as sv
  detections = sv.Detections(...)

• BoxAnnotator

  import supervision as sv
  annotator = sv.BoxAnnotator()

Quickstart

This quickstart demonstrates how to create dummy image data and detections, then use `sv.BoxAnnotator` to visualize them. This minimal example does not require an external deep learning model, only `numpy` and `opencv-python` (which are often installed automatically with `supervision[all]` or manually needed for CV tasks).

import supervision as sv
import numpy as np
import cv2

# Simulate an image (e.g., loaded from file or camera feed)
image_height, image_width = 720, 1280
image = np.zeros((image_height, image_width, 3), dtype=np.uint8)
cv2.rectangle(image, (100, 100), (300, 300), (255, 255, 255), -1)
cv2.putText(image, "Dummy Image", (500, 360), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)

# Simulate object detections (e.g., from a YOLO model)
detections = sv.Detections(
    xyxy=np.array([[150, 150, 250, 250], [500, 500, 600, 600]]),
    confidence=np.array([0.9, 0.8]),
    class_id=np.array([0, 1]),
    tracker_id=np.array([1, 2]),
    class_name=np.array(['person', 'car'])
)

# Create an annotator (e.g., for bounding boxes)
box_annotator = sv.BoxAnnotator(
    thickness=2, 
    text_thickness=2, 
    text_scale=1
)

# Annotate the image with the simulated detections
annotated_image = box_annotator.annotate(
    scene=image.copy(),
    detections=detections,
    labels=[f"Class {class_id} {confidence:.2f}" for class_id, confidence in zip(detections.class_id, detections.confidence)]
)

# In a real application, you would display or save 'annotated_image'
# For this quickstart, we'll print confirmation.
print(f"Annotated image shape: {annotated_image.shape}")
assert annotated_image.shape == image.shape
print("Supervision quickstart example ran successfully.")
# Example of saving the image:
# cv2.imwrite("annotated_output.jpg", annotated_image)