supervision-0.20.0

🚀 Added

• sv.KeyPoints to provide initial support for pose estimation and broader keypoint detection models. (#1128)

• sv.EdgeAnnotator and sv.VertexAnnotator to enable rendering of results from keypoint detection models. (#1128)

import cv2
import supervision as sv
from ultralytics import YOLO

image = cv2.imread(<SOURCE_IMAGE_PATH>)
model = YOLO('yolov8l-pose')

result = model(image, verbose=False)[0]
keypoints = sv.KeyPoints.from_ultralytics(result)

edge_annotators = sv.EdgeAnnotator(color=sv.Color.GREEN, thickness=5)
annotated_image = edge_annotators.annotate(image.copy(), keypoints)

import cv2
import supervision as sv
from ultralytics import YOLO

image = cv2.imread(<SOURCE_IMAGE_PATH>)
model = YOLO('yolov8l-pose')

result = model(image, verbose=False)[0]
keypoints = sv.KeyPoints.from_ultralytics(result)

vertex_annotators = sv.VertexAnnotator(color=sv.Color.GREEN, radius=10)
annotated_image = vertex_annotators.annotate(image.copy(), keypoints)

🌱 Changed

• sv.LabelAnnotator by adding an additional corner_radius argument that allows for rounding the corners of the bounding box. (#1037)

• sv.PolygonZone such that the frame_resolution_wh argument is no longer required to initialize sv.PolygonZone. (#1109)

Warning

The frame_resolution_wh parameter in sv.PolygonZone is deprecated and will be removed in supervision-0.24.0.

• sv.get_polygon_center to calculate a more accurate polygon centroid. (#1084)

• sv.Detections.from_transformers by adding support for Transformers segmentation models and extract class names values. (#1069)

import torch
import supervision as sv
from PIL import Image
from transformers import DetrImageProcessor, DetrForSegmentation

processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50-panoptic")
model = DetrForSegmentation.from_pretrained("facebook/detr-resnet-50-panoptic")

image = Image.open(<SOURCE_IMAGE_PATH>)
inputs = processor(images=image, return_tensors="pt")

with torch.no_grad():
    outputs = model(**inputs)

width, height = image.size
target_size = torch.tensor([[height, width]])
results = processor.post_process_segmentation(
    outputs=outputs, target_sizes=target_size)[0]
detections = sv.Detections.from_transformers(results, id2label=model.config.id2label)

mask_annotator = sv.MaskAnnotator()
label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)

annotated_image = mask_annotator.annotate(
    scene=image, detections=detections)
annotated_image = label_annotator.annotate(
    scene=annotated_image, detections=detections)

🛠️ Fixed

• sv.ByteTrack.update_with_detections which was removing segmentation masks while tracking. Now, ByteTrack can be used alongside segmentation models. (#787)

🏆 Contributors

@onuralpszr (Onuralp SEZER), @rolson24 (Raif Olson), @xaristeidou (Christoforos Aristeidou), @jeslinpjames (Jeslin P James), @Griffin-Sullivan (Griffin Sullivan), @PawelPeczek-Roboflow (Paweł Pęczek), @pirnerjonas (Jonas Pirner), @sharingan000, @macc-n, @LinasKo (Linas Kondrackis), @SkalskiP (Piotr Skalski)

supervision-0.19.0

🧑‍🍳 Cookbooks

Supervision Cookbooks - A curated open-source collection crafted by the community, offering practical examples, comprehensive guides, and walkthroughs for leveraging Supervision alongside diverse Computer Vision models. (#860)

🚀 Added

• sv.CSVSink allowing for the straightforward saving of image, video, or stream inference results in a .csv file. (#818)

import supervision as sv
from ultralytics import YOLO

model = YOLO(<SOURCE_MODEL_PATH>)
csv_sink = sv.CSVSink(<RESULT_CSV_FILE_PATH>)
frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)

with csv_sink:
    for frame in frames_generator:
        result = model(frame)[0]
        detections = sv.Detections.from_ultralytics(result)
        csv_sink.append(detections, custom_data={<CUSTOM_LABEL>:<CUSTOM_DATA>})

traffic_csv_2.mp4

• sv.JSONSink allowing for the straightforward saving of image, video, or stream inference results in a .json file. (#819)

import supervision as sv
from ultralytics import YOLO

model = YOLO(<SOURCE_MODEL_PATH>)
json_sink = sv.JSONSink(<RESULT_JSON_FILE_PATH>)
frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)

with json_sink:
    for frame in frames_generator:
        result = model(frame)[0]
        detections = sv.Detections.from_ultralytics(result)
        json_sink.append(detections, custom_data={<CUSTOM_LABEL>:<CUSTOM_DATA>})

• sv.mask_iou_batch allowing to compute Intersection over Union (IoU) of two sets of masks. (#847)
• sv.mask_non_max_suppression allowing to perform Non-Maximum Suppression (NMS) on segmentation predictions. (#847)
• sv.CropAnnotator allowing users to annotate the scene with scaled-up crops of detections. (#888)

import cv2
import supervision as sv
from inference import get_model

image = cv2.imread(<SOURCE_IMAGE_PATH>)
model = get_model(model_id="yolov8n-640")

result = model.infer(image)[0]
detections = sv.Detections.from_inference(result)

crop_annotator = sv.CropAnnotator()
annotated_frame = crop_annotator.annotate(
    scene=image.copy(),
    detections=detections
)

supervision-0.19.0-promo.mp4

🌱 Changed

• sv.ByteTrack.reset allowing users to clear trackers state, enabling the processing of multiple video files in sequence. (#827)
• sv.LineZoneAnnotator allowing to hide in/out count using display_in_count and display_out_count properties. (#802)
• sv.ByteTrack input arguments and docstrings updated to improve readability and ease of use. (#787)

Warning

The track_buffer, track_thresh, and match_thresh parameters in sv.ByterTrack are deprecated and will be removed in supervision-0.23.0. Use lost_track_buffer, track_activation_threshold, and minimum_matching_threshold instead.

• sv.PolygonZone to now accept a list of specific box anchors that must be in zone for a detection to be counted. (#910)

Warning

The triggering_position parameter in sv.PolygonZone is deprecated and will be removed in supervision-0.23.0. Use triggering_anchors instead.

• Annotators adding support for Pillow images. All supervision Annotators can now accept an image as either a numpy array or a Pillow Image. They automatically detect its type, draw annotations, and return the output in the same format as the input. (#875)

🛠️ Fixed

• sv.DetectionsSmoother removing tracking_id from sv.Detections. (#944)
• sv.DetectionDataset which, after changes introduced in supervision-0.18.0, failed to load datasets in YOLO, PASCAL VOC, and COCO formats.

🏆 Contributors

@onuralpszr (Onuralp SEZER), @LinasKo (Linas Kondrackis), @LeviVasconcelos (Levi Vasconcelos), @AdonaiVera (Adonai Vera), @xaristeidou (Christoforos Aristeidou), @Kadermiyanyedi (Kader Miyanyedi), @NickHerrig (Nick Herrig), @PacificDou (Shuyang Dou), @iamhatesz (Tomasz Wrona), @capjamesg (James Gallagher), @sansyo, @SkalskiP (Piotr Skalski)

supervision-0.18.0

🚀 Added

• sv.PercentageBarAnnotator allowing to annotate images and videos with percentage values representing confidence or other custom property. (#720)

import supervision as sv

image = ...
detections = sv.Detections(...)

percentage_bar_annotator = sv.PercentageBarAnnotator()
annotated_frame = percentage_bar_annotator.annotate(
    scene=image.copy(),
    detections=detections
)

• sv.RoundBoxAnnotator allowing to annotate images and videos with rounded corners bounding boxes. (#702)
• sv.DetectionsSmoother allowing for smoothing detections over multiple frames in video tracking. (#696)

supervision-detection-smoothing.mp4

• sv.OrientedBoxAnnotator allowing to annotate images and videos with OBB (Oriented Bounding Boxes). (#770)

import cv2
import supervision as sv
from ultralytics import YOLO

image = cv2.imread(<SOURCE_IMAGE_PATH>)
model = YOLO("yolov8n-obb.pt")

result = model(image)[0]
detections = sv.Detections.from_ultralytics(result)

oriented_box_annotator = sv.OrientedBoxAnnotator()
annotated_frame = oriented_box_annotator.annotate(
    scene=image.copy(),
    detections=detections
)

• sv.ColorPalette.from_matplotlib allowing users to create a sv.ColorPalette instance from a Matplotlib color palette. (#769)

import supervision as sv

sv.ColorPalette.from_matplotlib('viridis', 5)
# ColorPalette(colors=[Color(r=68, g=1, b=84), Color(r=59, g=82, b=139), ...])

🌱 Changed

• sv.Detections.from_ultralytics adding support for OBB (Oriented Bounding Boxes). (#770)
• sv.LineZone to now accept a list of specific box anchors that must cross the line for a detection to be counted. This update marks a significant improvement from the previous requirement, where all four box corners were necessary. Users can now specify a single anchor, such as sv.Position.BOTTOM_CENTER, or any other combination of anchors defined as List[sv.Position]. (#735)
• sv.Detections to support custom payload. (#700)
• sv.Color's and sv.ColorPalette's method of accessing predefined colors, transitioning from a function-based approach (sv.Color.red()) to a more intuitive and conventional property-based method (sv.Color.RED). (#756) (#769)

Warning

sv.ColorPalette.default() is deprecated and will be removed in supervision-0.21.0. Use sv.ColorPalette.DEFAULT instead.

• sv.ColorPalette.DEFAULT value, giving users a more extensive set of annotation colors. (#769)

• sv.Detections.from_roboflow to sv.Detections.from_inference streamlining its functionality to be compatible with both the both inference pip package and the Roboflow hosted API. (#677)

Warning

Detections.from_roboflow() is deprecated and will be removed in supervision-0.21.0. Use Detections.from_inference instead.

import cv2
import supervision as sv
from inference.models.utils import get_roboflow_model

image = cv2.imread(<SOURCE_IMAGE_PATH>)
model = get_roboflow_model(model_id="yolov8s-640")

result = model.infer(image)[0]
detections = sv.Detections.from_inference(result)

🛠️ Fixed

• sv.LineZone functionality to accurately update the counter when an object crosses a line from any direction, including from the side. This enhancement enables more precise tracking and analytics, such as calculating individual in/out counts for each lane on the road. (#735)

supervision-0.18.0-promo-sample-2-result.mp4

🏆 Contributors

@onuralpszr (Onuralp SEZER), @HinePo (Rafael Levy), @xaristeidou (Christoforos Aristeidou), @revtheundead (Utku Özbek), @paulguerrie (Paul Guerrie), @yeldarby (Brad Dwyer), @capjamesg (James Gallagher), @SkalskiP (Piotr Skalski)

supervision-0.17.1

🚀 Added

• Support for Python 3.12.

🏆 Contributors

@onuralpszr (Onuralp SEZER), @SkalskiP (Piotr Skalski)

supervision-0.17.0

🚀 Added

• sv.PixelateAnnotator allowing to pixelate objects on images and videos. (#633)

walking-pixelate-corner-optimized.mp4

• sv.TriangleAnnotator allowing to annotate images and videos with triangle markers. (#652)

• sv.PolygonAnnotator allowing to annotate images and videos with segmentation mask outline. (#602)

  >>> import supervision as sv
  
  >>> image = ...
  >>> detections = sv.Detections(...)
  
  >>> polygon_annotator = sv.PolygonAnnotator()
  >>> annotated_frame = polygon_annotator.annotate(
  ...     scene=image.copy(),
  ...     detections=detections
  ... )

walking-polygon-optimized.mp4

• sv.assets allowing download of video files that you can use in your demos. (#476)

  >>> from supervision.assets import download_assets, VideoAssets
  >>> download_assets(VideoAssets.VEHICLES)
  "vehicles.mp4"

• Position.CENTER_OF_MASS allowing to place labels in center of mass of segmentation masks. (#605)

• sv.scale_boxes allowing to scale sv.Detections.xyxy values. (#651)

• sv.calculate_dynamic_text_scale and sv.calculate_dynamic_line_thickness allowing text scale and line thickness to match image resolution. (#637)

• sv.Color.as_hex allowing to extract color value in HEX format. (#620)

• sv.Classifications.from_timm allowing to load classification result from timm models. (#572)

• sv.Classifications.from_clip allowing to load classification result from clip model. (#478)

• sv.Detections.from_azure_analyze_image allowing to load detection results from Azure Image Analysis. (#571)

🌱 Changed

• sv.BoxMaskAnnotator renaming it to sv.ColorAnnotator. (#646)

• sv.MaskAnnotator to make it 5x faster. (#606)

🛠️ Fixed

• sv.DetectionDataset.from_yolo to ignore empty lines in annotation files. (#584)

• sv.BlurAnnotator to trim negative coordinates before bluring detections. (#555)

• sv.TraceAnnotator to respect trace position. (#511)

🏆 Contributors

@onuralpszr (Onuralp SEZER), @hugoles (Hugo Dutra), @karanjakhar (Karan Jakhar), @kim-jeonghyun (Jeonghyun Kim), @fdloopes (
Felipe Lopes), @abhishek7kalra (Abhishek Kalra), @SummitStudiosDev, @xenteros @capjamesg (James Gallagher), @SkalskiP (Piotr Skalski)

supervision-0.16.0

🚀 Added

supervision-0.16.0-annotators.mp4

• sv.BoxMaskAnnotator allowing to annotate images and videos with mox masks. (#422)
• sv.HaloAnnotator allowing to annotate images and videos with halo effect. (#433)

>>> import supervision as sv

>>> image = ...
>>> detections = sv.Detections(...)

>>> halo_annotator = sv.HaloAnnotator()
>>> annotated_frame = halo_annotator.annotate(
...     scene=image.copy(),
...     detections=detections
... )

• sv.HeatMapAnnotator allowing to annotate videos with heat maps. (#466)
• sv.DotAnnotator allowing to annotate images and videos with dots. (#492)
• sv.draw_image allowing to draw an image onto a given scene with specified opacity and dimensions. (#449)
• sv.FPSMonitor for monitoring frames per second (FPS) to benchmark latency. (#280)
• 🤗 Hugging Face Annotators space. (#454)

🌱 Changed

• sv.LineZone.trigger now return Tuple[np.ndarray, np.ndarray]. The first array indicates which detections have crossed the line from outside to inside. The second array indicates which detections have crossed the line from inside to outside. (#482)
• Annotator argument name from color_map: str to color_lookup: ColorLookup enum to increase type safety. (#465)
• sv.MaskAnnotator allowing 2x faster annotation. (#426)

🛠️ Fixed

• Poetry env definition allowing proper local installation. (#477)
• sv.ByteTrack to return np.array([], dtype=int) when svDetections is empty. (#430)
• YOLONAS detection missing predication part added & fixed (#416)
• SAM detection at Demo Notebook MaskAnnotator(color_map="index") color_map set to index (#416)

🗑️ Deleted

Warning
Deleted sv.Detections.from_yolov8 and sv.Classifications.from_yolov8 as those are now replaced by sv.Detections.from_ultralytics and sv.Classifications.from_ultralytics. (#438)

🏆 Contributors

@hardikdava (Hardik Dava), @onuralpszr (Onuralp SEZER), @kapter, @keshav278 (Keshav Subramanian), @akashpambhar (Akash Pambhar), @AntonioConsiglio (Antonio Consiglio), @ashishdatta, @mario-dg (Mario da Graca), @ jayaBalaR (JAYABALAMBIKA.R), @abhishek7kalra (Abhishek Kalra), @PankajKrana (Pankaj Kumar Rana), @capjamesg (James Gallagher), @SkalskiP (Piotr Skalski)

supervision-0.15.0

🚀 Added

supervision-0.15.0.mp4

• sv.LabelAnnotator allowing to annotate images and videos with text. (#170)

• sv.BoundingBoxAnnotator allowing to annotate images and videos with bounding boxes. (#170)

• sv.BoxCornerAnnotator allowing to annotate images and videos with just bounding box corners. (#170)

• sv.MaskAnnotator allowing to annotate images and videos with segmentation masks. (#170)

• sv.EllipseAnnotator allowing to annotate images and videos with ellipses (sports game style). (#170)

• sv.CircleAnnotator allowing to annotate images and videos with circles. (#386)

• sv.TraceAnnotator allowing to draw path of moving objects on videos. (#354)

• sv.BlurAnnotator allowing to blur objects on images and videos. (#405)

>>> import supervision as sv

>>> image = ...
>>> detections = sv.Detections(...)

>>> bounding_box_annotator = sv.BoundingBoxAnnotator()
>>> annotated_frame = bounding_box_annotator.annotate(
...     scene=image.copy(),
...     detections=detections
... )

• Supervision usage example. You can now learn how to perform traffic flow analysis with Supervision. (#354)

traffic_analysis_result.mov

🌱 Changed

• sv.Detections.from_roboflow now does not require class_list to be specified. The class_id value can be extracted directly from the inference response. (#399)

• sv.VideoSink now allows to customize the output codec. (#381)

• sv.InferenceSlicer can now operate in multithreading mode. (#361)

🛠️ Fixed

• sv.Detections.from_deepsparse to allow processing empty deepsparse result object. (#348)

🏆 Contributors

@hardikdava (Hardik Dava), @onuralpszr (Onuralp SEZER), @Killua7362 (Akshay Bhat), @fcakyon (Fatih C. Akyon), @akashAD98 (Akash A Desai), @Rajarshi-Misra (Rajarshi Misra), @capjamesg (James Gallagher), @SkalskiP (Piotr Skalski)

supervision-0.14.0

🚀 Added

• Support for SAHI inference technique with sv.InferenceSlicer. (#282)

>>> import cv2
>>> import supervision as sv
>>> import numpy as np
>>> from ultralytics import YOLO

>>> image = cv2.imread(SOURCE_IMAGE_PATH)
>>> model = YOLO(...)

>>> def callback(image_slice: np.ndarray) -> sv.Detections:
...     result = model(image_slice)[0]
...     return sv.Detections.from_ultralytics(result)

>>> slicer = sv.InferenceSlicer(callback = callback)

>>> detections = slicer(image)

inference-slicer.mov

• Detections.from_deepsparse to enable seamless integration with DeepSparse framework. (#297)

• sv.Classifications.from_ultralytics to enable seamless integration with Ultralytics framework. This will enable you to use supervision with all models that Ultralytics supports. (#281)

  Warning
  sv.Detections.from_yolov8 and sv.Classifications.from_yolov8 are now deprecated and will be removed with supervision-0.16.0 release.

• First supervision usage example script showing how to detect and track objects on video using YOLOv8 + Supervision. (#341)

detect-and-track-objects-on-video.mov

🌱 Changed

• sv.ClassificationDataset and sv.DetectionDataset now use image path (not image name) as dataset keys. (#296)

🛠️ Fixed

• Detections.from_roboflow to filter out polygons with less than 3 points. (#300)

🏆 Contributors

@hardikdava (Hardik Dava), @onuralpszr (Onuralp SEZER), @mayankagarwals (Mayank Agarwal), @rizavelioglu (Riza Velioglu), @arjun-234 (Arjun D.), @mwitiderrick (Derrick Mwiti), @ShubhamKanitkar32, @gasparitiago (Tiago De Gaspari), @capjamesg (James Gallagher), @SkalskiP (Piotr Skalski)

supervision-0.13.0

🚀 Added

• Support for mean average precision (mAP) for object detection models with sv.MeanAveragePrecision. (#236)

>>> import supervision as sv
>>> from ultralytics import YOLO

>>> dataset = sv.DetectionDataset.from_yolo(...)

>>> model = YOLO(...)
>>> def callback(image: np.ndarray) -> sv.Detections:
...     result = model(image)[0]
...     return sv.Detections.from_yolov8(result)

>>> mean_average_precision = sv.MeanAveragePrecision.benchmark(
...     dataset = dataset,
...     callback = callback
... )

>>> mean_average_precision.map50_95
0.433

• Support for ByteTrack for object tracking with sv.ByteTrack. (#256)

>>> import supervision as sv
>>> from ultralytics import YOLO

>>> model = YOLO(...)
>>> byte_tracker = sv.ByteTrack()
>>> annotator = sv.BoxAnnotator()

>>> def callback(frame: np.ndarray, index: int) -> np.ndarray:
...     results = model(frame)[0]
...     detections = sv.Detections.from_yolov8(results)
...     detections = byte_tracker.update_from_detections(detections=detections)
...     labels = [
...         f"#{tracker_id} {model.model.names[class_id]} {confidence:0.2f}"
...         for _, _, confidence, class_id, tracker_id
...         in detections
...     ]
...     return annotator.annotate(scene=frame.copy(), detections=detections, labels=labels)

>>> sv.process_video(
...     source_path='...',
...     target_path='...',
...     callback=callback
... )

byte_track_result_small.mp4

• sv.Detections.from_ultralytics to enable seamless integration with Ultralytics framework. This will enable you to use supervision with all models that Ultralytics supports. (#222)

  Warning
  sv.Detections.from_yolov8 is now deprecated and will be removed with supervision-0.15.0 release.

• sv.Detections.from_paddledet to enable seamless integration with PaddleDetection framework. (#191)

• Support for loading PASCAL VOC segmentation datasets with sv.DetectionDataset.. (#245)

🏆 Contributors

@hardikdava (Hardik Dava), @kirilllzaitsev (Kirill Zaitsev), @onuralpszr (Onuralp SEZER), @dbroboflow, @mayankagarwals (Mayank Agarwal), @danigarciaoca (Daniel M. García-Ocaña), @capjamesg (James Gallagher), @SkalskiP (Piotr Skalski)

supervision-0.12.0

Warning
With the supervision-0.12.0 release, we are terminating official support for Python 3.7. (#179)

🚀 Added

• Initial support for object detection model benchmarking with sv.ConfusionMatrix. (#177)

>>> import supervision as sv
>>> from ultralytics import YOLO

>>> dataset = sv.DetectionDataset.from_yolo(...)

>>> model = YOLO(...)
>>> def callback(image: np.ndarray) -> sv.Detections:
...     result = model(image)[0]
...     return sv.Detections.from_yolov8(result)

>>> confusion_matrix = sv.ConfusionMatrix.benchmark(
...     dataset = dataset,
...     callback = callback
... )

>>> confusion_matrix.matrix
array([
    [0., 0., 0., 0.],
    [0., 1., 0., 1.],
    [0., 1., 1., 0.],
    [1., 1., 0., 0.]
])

• Detections.from_mmdetection to enable seamless integration with MMDetection framework. (#173)

• Ability to install package in headless or desktop mode. (#130)

🌱 Changed

• Packing method from setup.py to pyproject.toml. (#180)

🛠️ Fixed

• sv.DetectionDataset.from_cooc can't be loaded when there are images without annotations. (#188)
• sv.DetectionDataset.from_yolo can't load background instances. (#226)

🏆 Contributors

@kirilllzaitsev @hardikdava @onuralpszr @Ucag @SkalskiP @capjamesg