roboflow/supervision

Supervision is a Python library that provides foundational tools for processing and visualizing computer vision inference results, including object detection, classification, and pose estimation. It offers a unified API for handling detection data, performing geometry-aware calculations like IoU and NMS, and rendering annotations on images and videos. The system supports multiple dataset formats and integrates with various model backends to facilitate tasks such as tracking, zone-based counting, and performance evaluation.

14 changes.

The project established its core development infrastructure, including testing, documentation, and dependency management, while removing initial placeholder code. It then focused on expanding the library's utility by adding comprehensive test coverage for validation and drawing modules. Finally, the period saw the creation of a wide array of practical examples for tracking, traffic analysis, and crowd monitoring, supporting multiple detection backends.

33 changes.

This period established the core structure of the supervision library, introducing foundational modules for geometry, detection, classification, and key points. It significantly expanded functionality with new tools for dataset handling, metrics evaluation, and memory-efficient mask storage, while removing the OpenCV dependency in favor of NumPy and Pillow backends.

The \src/supervision/assets\ module now provides a \download\_assets\ function and \ImageAssets\/\VideoAssets\ enums, allowing users to programmatically download example media files (such as \vehicles.mp4\ or \people-walking.jpg\) directly from Roboflow's media server. The implementation includes MD5-based integrity checks to detect and automatically re-download corrupted files, ensuring reliable access to sample data for testing and demos.

src/supervision/assets · high confidence

The \examples/heatmap\_and\_track\ directory now includes a new demo that performs crowd analysis using object detection and ByteTrack multi-object tracking. Users can run the example with the recommended RF-DETR model (\rfdetr\_example.py\) or with YOLOv8 via Ultralytics (\script.py\), both of which generate heatmaps and track person IDs in video footage. The example provides CLI arguments for configuring detection thresholds, heatmap appearance, and tracking parameters, and includes a README with installation and usage instructions.

_examples/heatmap\_and\track · high confidence

The dataset loader now supports CreateML and LabelMe annotation formats in addition to the existing COCO, Pascal VOC, and YOLO formats. CreateML annotations are loaded from a single JSON file containing bounding boxes defined by center coordinates, while LabelMe annotations are loaded from per-image JSON files supporting both rectangle and polygon shapes, with optional mask generation. Both formats include path validation to prevent directory traversal and handle class mapping consistently with other supported formats.

src/supervision/dataset/formats · high confidence

New example scripts in the \examples/compact\_mask\ directory demonstrate the performance and memory benefits of the \CompactMask\ implementation. \benchmark.py\ provides a comprehensive comparison of dense versus compact mask handling, measuring metrics such as memory usage, encoding/decoding time, and operations like IoU, NMS, and annotation speed across various scene complexities. \bench\_inference\_api.py\ offers a practical benchmark for ingesting RLE masks from inference APIs, allowing users to validate the memory and speed improvements in a real-world inference pipeline context.

supervision · high confidence

The repository has been initialized with the core structure for the \supervision\ library, including the \src/supervision/\ package source, \tests/\ directory, and a \demo.ipynb\ quickstart notebook. Development workflow is established via a comprehensive \.pre-commit-config.yaml\ enforcing code quality with \ruff\, \mypy\, \docformatter\, and \mdformat\, alongside \uv.lock\ for dependency management requiring Python 3.10+. Documentation is configured using \mkdocs.yml\ with Material theme, \mkdocstrings\, and \mike\ for versioning, while CI coverage is set up via \.codecov.yml\ and multi-version testing via \tox.ini\. Project metadata and guidelines are provided through \LICENSE.md\, \CITATION.cff\, \AGENTS.md\, and \CLAUDE.md\.

(repo-wide) · high confidence

The detection module now includes a new CompactMask class for memory-efficient storage of instance segmentation masks using run-length encoding of bounding-box crops, significantly reducing memory usage for large images with many sparse masks. Additionally, a centralized geometry-aware dispatch system has been added to automatically select the most precise calculation method for detection area and IoU based on available geometry (masks, oriented boxes, or axis-aligned boxes), ensuring accurate measurements regardless of the detection type.

src/supervision/detection · high confidence

The dataset module now provides a new DetectionDataset class that handles lazy image loading and annotation retrieval, supporting import and export for COCO, YOLO, Pascal VOC, CreateML, and LabelMe formats. To prevent data loss during export, the implementation includes strict validation that rejects filename collisions when multiple images share the same basename, and it correctly handles EXIF orientation tags to ensure images are sized as they load. Additionally, the dataset split functionality has been hardened to reject invalid ratios and prevent mutation of the original dataset state.

src/supervision/dataset · high confidence

Added a new \src/supervision/key\_points\ package containing the \KeyPoints\ data class for standardizing pose estimation results, conversion bridges for Ultralytics, Inference, and MediaPipe inputs, and \VertexAnnotator\ and \EdgeAnnotator\ classes for drawing skeletons on images. The annotators now skip non-finite coordinates and respect visibility masks to prevent rendering errors on occluded or undetected keypoints.

_src/supervision/key\points · high confidence

This change introduces the \supervision.geometry\ module, providing foundational 2D geometry types including \Point\, \Vector\, and \Rect\ with methods for coordinate conversion and spatial operations. It also adds a \get\_polygon\_center\ utility function that calculates the centroid of a polygon using a signed-area weighted algorithm, addressing potential overflow issues in previous implementations.

src/supervision/geometry · high confidence

A new \Classifications\ dataclass has been introduced in the \supervision.classification\ module to standardize how classification outputs are handled. This component provides factory methods (\from\_clip\, \from\_ultralytics\, \from\_timm\) to convert inference results from OpenAI CLIP, Ultralytics, and Hugging Face Timm models into a consistent structure containing class IDs and confidence scores. It also includes utility methods like \get\_top\_k\ for retrieving the highest-confidence predictions, allowing users to work with classification data from various model backends using a single, unified interface.

src/supervision/classification · high confidence

Added an example in \examples/compact\_mask\ that benchmarks \CompactMask\, a new mask representation replacing dense \(N, H, W)\ boolean arrays with crop-scoped Run-Length Encoding (RLE). The included \README.md\ details the memory and performance benefits for high-density scenes, while \benchmark\_nmm.py\ provides reproducible measurements for Non-Maximum Suppression (NMM) operations using this compact format.

_examples/compact\mask · high confidence

The \examples/count\_people\_in\_zone\ directory now provides a complete, runnable demo for counting objects within configurable polygonal zones in video. It includes three distinct entry points—\rfdetr\_example.py\, \ultralytics\_example.py\, and \inference\_example.py\—allowing users to choose between RF-DETR, YOLO (Ultralytics), or Roboflow Inference models. The scripts have been updated to use \sv.calculate\_optimal\_line\_thickness\ and \sv.calculate\_optimal\_text\_scale\ for better annotation scaling, and they expose CLI arguments (via \jsonargparse\) for \confidence\_threshold\ and \iou\_threshold\, enabling users to tune detection filtering and non-maximum suppression directly from the command line.

_examples/count\_people\_in\zone · high confidence

This release introduces a suite of new tools in the \supervision.detection.tools\ module to improve detection data handling. \CSVSink\ and \JSONSink\ provide structured serialization of detection results to CSV and JSON files, with support for per-row custom data and proper handling of NumPy types. \InferenceSlicer\ enables tiled inference on large images, supporting batched callbacks, multi-threading, and memory-efficient \CompactMask\ storage. \PolygonZone\ and \PolygonZoneAnnotator\ allow for zone-based detection counting with configurable anchor logic. \DetectionsSmoother\ stabilizes tracking results over time, while \transformers.py\ adds robust processing for Hugging Face Transformers v4 and v5 detection and segmentation outputs.

src/supervision/detection/tools · high confidence

The \src/supervision/metrics/utils\ module now provides utilities for combining and analyzing metric results. Users can aggregate multiple \MetricResult\ objects into a single pandas DataFrame or generate a grouped bar chart comparing models, with an option to include small/medium/large object-size categories. Additionally, the module introduces \ObjectSizeCategory\ and helper functions to classify detections by area (using thresholds of 32² and 96² pixels) for bounding boxes, masks, and oriented bounding boxes, supporting size-bucketed metric analysis.

src/supervision/metrics/utils · high confidence

The \examples/speed\_estimation\ directory now provides a complete, runnable demo for estimating vehicle speed from video using object detection and tracking. It includes dedicated scripts for four backends: RF-DETR (recommended), Ultralytics (YOLOv8/YOLO11), Roboflow Inference, and a legacy YOLO-NAS reference. The example uses ByteTrack for multi-object tracking, \PolygonZone\ and \ViewTransformer\ for perspective-corrected ground-plane coordinate mapping, and Supervision annotators (\BoxAnnotator\, \LabelAnnotator\, \TraceAnnotator\) to display tracked IDs and calculated speeds (km/h) in real-time or saved output videos. A \video\_downloader.py\ script and \.gitignore\ are included to simplify setup, and the README documents configuration of SOURCE/TARGET polygons, CLI arguments, and licensing for each model variant.

_examples/speed\estimation · high confidence

The time\_in\_zone example has been updated to include new scripts for running object detection and dwell-time analysis using RF-DETR and Ultralytics YOLO models, in addition to the existing Roboflow Inference support. The example now provides separate entry points for processing video files and RTSP streams, with variants that use either a naive frame-polling approach or the InferencePipeline for background processing. Users can now configure model sizes (nano, small, medium, base, large), select computation devices (cpu, mps, cuda), and adjust input resolutions for RF-DETR, while all scripts support filtering by class, confidence, and IoU thresholds, and display real-time tracking IDs with elapsed time in the defined zones.

_examples/time\_in\zone · high confidence

The \examples/tracking\ directory now includes three new scripts (\rfdetr\_example.py\, \ultralytics\_example.py\, and \inference\_example.py\) that demonstrate video processing with object detection and tracking using RF-DETR, YOLOv8 (via Ultralytics), and Roboflow Inference respectively. Each example uses the \ByteTrackTracker\ to assign persistent IDs to detected objects and \supervision\ annotators to visualize bounding boxes and labels on the output video. The examples support configurable confidence and IoU thresholds, accept source video and target output paths via CLI arguments (parsed using \jsonargparse\), and include a \README.md\ with installation and usage instructions.

examples/tracking · high confidence

A new \examples/traffic\_analysis\ directory has been added, providing a complete demo for traffic flow analysis using object detection and ByteTrack multi-object tracking. The example includes three variants—RF-DETR, Ultralytics (YOLOv8), and Roboflow Inference—each capable of counting vehicles as they transition between defined entry and exit polygon zones. It leverages the \supervision\ library for zone triggering, annotation (boxes, labels, traces), and video I/O, and includes a setup script to download sample data and a README detailing installation and CLI arguments.

_examples/traffic\analysis · high confidence

Added new utility files (\general.py\, \timers.py\) to the \examples/time\_in\_zone/utils\ package to support the time-in-zone and dwell-time demonstration. \general.py\ provides helper functions for loading polygon zone configurations from JSON files, checking array membership, and generating frames from RTSP video streams. \timers.py\ introduces two timer classes, \FPSBasedTimer\ and \ClockBasedTimer\, which calculate the duration objects remain detected in a zone based on either frame counts or system clock time.

_examples/time\_in\zone/utils · high confidence

The Time in Zone example now includes three new helper scripts to streamline setup and annotation workflows. Users can download source videos directly from YouTube using \download\_from\_youtube.py\, interactively draw and save polygon zone configurations on images or video frames via \draw\_zones.py\, and stream local video files over RTSP using \stream\_from\_file.py\ (which manages an RTSP server via Docker). These tools simplify the process of preparing data and defining detection zones for the demo.

_examples/time\_in\zone/scripts · high confidence

This change establishes the \src/supervision\ package structure by creating the main \\_\init\\_.py\ entry point, which exposes a comprehensive set of public API components including annotators, detection utilities, dataset classes, and key-point tools. It also introduces \config.py\ to define standard metadata field names (such as \CLASS\_NAME\_DATA\_FIELD\, \AREA\_DATA\_FIELD\, and \ORIENTED\_BOX\_COORDINATES\) used across the library for detection data handling, alongside a \py.typed\ marker file to enable static type checking for the package.

src/supervision · high confidence

The \src/\_\init\\_.py\ and \src/hello.py\ files have been deleted from the project. This removes the package version definition (previously 0.0.5) and the \hello()\ function that returned the string "World", effectively stripping the main source code from this location.

src · high confidence

The detection utility functions have been reorganized from the top-level detection module into a new \src/supervision/detection/utils\ package. This change introduces a modular structure with dedicated files for specific concerns: \boxes.py\ for bounding box operations (clipping, padding, normalization), \converters.py\ for coordinate format conversions (xyxy, xywh, xcycwh) and polygon-to-mask generation, \masks.py\ for mask manipulation and centroid calculation, \iou\_and\_nms.py\ for overlap metrics and non-maximum suppression/merging, \polygons.py\ for polygon approximation and area filtering, \matching.py\ for public detection matching primitives, and \vlms.py\ for string matching utilities. Type definitions and internal helpers have also been moved into \\_typing.py\ and \internal.py\ respectively, improving code organization and maintainability without altering the public API surface.

src/supervision/detection/utils · high confidence

The annotation system has been restructured to improve performance and usability. A new \BaseAnnotator\ class introduces a \requires\_mask\ attribute, allowing integrations to check for mask availability before materializing expensive payloads. Pixel and kernel sizes are now dynamic, adapting to the scene resolution. Memory usage is reduced through the introduction of \CompactMask\ for efficient crop-RLE mask storage and optimized mask blending. Additionally, several bugs were fixed: \CropAnnotator\ and \BackgroundOverlayAnnotator\ now correctly clip boxes to the scene, \HeatMapAnnotator\ avoids divide-by-zero errors on empty detections, and \TraceAnnotator\ handles stationary tracker IDs and empty frames more robustly.

src/supervision/annotators · high confidence

The \src/supervision/metrics\ package has been restructured to provide a modern, unified API for object detection evaluation. This change introduces a new \Metric\ and \MetricResult\ abstract base class hierarchy, replacing legacy implementations. The module now includes \MeanAveragePrecision\, \MeanAverageRecall\, \Precision\, \Recall\, and \F1Score\, all of which support \MetricTarget\ for boxes, masks, and oriented bounding boxes (OBB). Key behavioral improvements include COCO-compliant matching logic (using greedy algorithms and top-K detection limits for mAR@K), size-bucketed analysis (small/medium/large objects), and robust handling of edge cases such as empty ground-truth images and prediction-only classes. The new API also standardizes result visualization and pandas export capabilities across all metrics.

src/supervision/metrics · high confidence

A new \src/supervision/validators\ module has been introduced to centralize input validation for detection objects. This module provides internal helper functions (prefixed with \\validate\\) that enforce strict shape and type constraints for bounding boxes (\xyxy\), masks, class IDs, confidence scores, keypoint confidence, and tracker IDs. Public-facing wrapper functions (e.g., \validate\_xyxy\) are marked as deprecated and will be removed in version 0.32.0, signaling a shift toward using the new internal validation logic directly within the library's core components.

src/supervision/validators · high confidence

The supervision library introduces a new, modular drawing API under the \src/supervision/draw\ package, replacing the previous monolithic structure. This update provides a dedicated \Color\ class that supports hexadecimal RGBA formats (including 3, 4, 6, and 8-digit codes) and validates RGB/BGR values, alongside a consistent \ImageType\ type variable for better type safety with NumPy and PIL images. The new module includes utility functions for drawing lines, rectangles, and rounded rectangles, and fixes the handling of 16-bit images by scaling them down during drawing operations.

src/supervision/draw · high confidence

The library no longer requires the \opencv-python\ package to function. If OpenCV is not installed, the \src/supervision/\_cv2\ compatibility layer automatically switches to a pure NumPy and Pillow backend for image operations (color conversion, resizing, drawing, text rendering) and uses PyAV for video capture and writing. This removes the heavy C++ dependency while maintaining the same public API, though some operations may be slower or exhibit minor visual differences in text and drawing.

_src/supervision/\cv2 · high confidence

The \src/supervision/utils\ package has been reorganized into dedicated modules (\conversion.py\, \file.py\, \image.py\, \image\_window.py\, \internal.py\, \iterables.py\, \logger.py\, \notebook.py\, \video.py\) to improve code structure and maintainability. A new \load\_image\_from\_url\ function allows users to fetch and cache images directly from HTTP(S) sources, while the new \ImageWindow\ class provides a desktop preview window using Tkinter and Pillow, enabling visual debugging without requiring a full OpenCV GUI backend. Image conversion utilities have been updated to robustly handle all Pillow modes (including high-bit-depth and palette images) by converting them to standard 8-bit BGR or grayscale layouts, and \VideoInfo.fps\ now returns a float to preserve sub-frame-rate precision.

src/supervision/utils · high confidence

Added comprehensive test coverage for dataset operations; Added comprehensive test coverage for detection module; Added comprehensive test coverage for detection tools; Added comprehensive test suite for annotators; Added comprehensive test suite for the OpenCV fallback backend; Added comprehensive test suite for utility modules; Added test coverage for geometry core and utility functions; Added test infrastructure and coverage for validation deprecations; Added tests for asset download and listing functionality; Added tests for classification core functionality; Added tests for drawing utilities and color handling; Added tests for metrics utility functions; Comprehensive test coverage for dataset format loaders and exporters; Comprehensive test coverage for detection utility functions; Comprehensive test suite for metrics module; Initial test coverage for key points and annotators; Removal of hello module test suite.

The Supervision package has been updated to version 0.31.0.dev0, raising the minimum supported Python version to 3.10 (supporting up to 3.14). The core dependencies now include av\>=14.2, defusedxml\>=0.7.1, and pydeprecate\>=0.9,\<0.13, while maintaining existing requirements for matplotlib, numpy, pillow, pyyaml, requests, scipy, and tqdm. New optional dependency groups have been added for geotiff (rasterio) and metrics (pandas). Additionally, dedicated requirements.txt files have been introduced for all example scripts (compact\_mask, count\_people\_in\_zone, heatmap\_and\_track, speed\_estimation, time\_in\_zone, tracking, traffic\_analysis), specifying their specific dependencies such as inference, rfdetr, ultralytics, and trackers.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 58.

• Code Health 98
• Architecture 100
• Maturity 59
• Readiness 43
• Security 75

• 300 commits — 187 feature/other, 113 fixes

• src/supervision — 116 commits
• docs/changelog.md — 75 commits
• (root) — 62 commits
• .github/workflows — 14 commits
• tests/detection — 7 commits
• .github/_tests — 6 commits
• docs/how_to — 4 commits
• examples/time_in_zone — 3 commits
• tests/cv2 — 2 commits
• tests/dataset — 2 commits
• .github/CONTRIBUTING.md — 1 commit
• .github/PULL_REQUEST_TEMPLATE.md — 1 commit
• .github/dependabot.yml — 1 commit
• .github/lychee.toml — 1 commit
• docs/notebooks — 1 commit
• examples/compact_mask — 1 commit
• examples/count_people_in_zone — 1 commit
• examples/traffic_analysis — 1 commit
• tests/metrics — 1 commit

• fix: fix(annotators): clip BackgroundOverlayAnnotator boxes to the scene… (#2396)
• fix: fix(metrics): ignore out-of-bucket detections in size-bucketed sco… (#2428)
• fix: fix: replace deprecated 2-D np.cross with explicit determinant (#2386)
• fix: Fix polygon_to_mask crash on list vertices or empty polygons (#2622)
• fix: Fix detection medium review findings (#2400)
• fix: Fix ellipse annotators to draw level-by-level instead of point-by-point (#2325)
• fix: Fix hex parser accepting multiple leading prefixes (#2421)
• fix: Fix sink state when instances are reopened (#2459)
• fix: Fix: resolve major complex review (#2388)
• fix: fix(LineZone): ignore unconfirmed tracks with a negative tracker_id (#2623)
• fix: fix(_cv2): lazy-import PyAV to avoid duplicate libavdevice load (#2509)
• fix: fix(annotators): clip CropAnnotator boxes to the scene before cropping (#2391)
• fix: fix(annotators): clip crops, fix heatmap wrap, release capture (#2393)
• fix: fix(annotators): draw grayscale PNG icons in IconAnnotator (#2591)
• fix: fix(annotators): keep TraceAnnotator's custom color lookup aligned with pending tracks (#2586)
• fix: fix(annotators): resolve annotator medium findings (#2407)
• fix: fix(ci): always delete mike latest before redeploying docs (#2513)
• fix: fix(ci): clear latest alias before deploying docs to release/latest (#2340)
• fix: fix(coco): preserve segmentation in as_coco() round-trip (#2321)
• fix: fix(cv2): pad getTextSize height/baseline from actual stroke_width
• …and 280 more

• 0 containers · 1 bounded contexts · 0 dependency edges (baseline)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

roboflow/supervision was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.