diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 05b726e8..f1c65fa6 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -56,5 +56,56 @@ jobs: env: MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }} run: | - latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`) + latest_tag=$(git tag --sort=-v:refname | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | head -1) mike deploy --push --update-aliases $latest_tag latest + + # IndexNow key: 0d5d9799b1cc4a39825146388c6781eb + # This key must stay in sync across three files: + # docs/0d5d9799b1cc4a39825146388c6781eb.txt (key file served at site root) + # docs/theme/main.html (indexnow-key meta tag) + # this workflow (inject step + notify step below) + # Bing/Yandex fetch https://supervision.roboflow.com/.txt to verify ownership. + # Do NOT rename or delete the .txt file or change the key string without updating all three. + - name: 🌐 Inject GEO root files into gh-pages + if: > + (github.event_name == 'push' && github.ref == 'refs/heads/develop') || + github.event_name == 'workflow_dispatch' || + (github.event_name == 'release' && github.event.action == 'published') + run: | + cp docs/robots.txt /tmp/robots.txt + cp docs/llms.txt /tmp/llms.txt + cp docs/0d5d9799b1cc4a39825146388c6781eb.txt /tmp/indexnow.txt + git fetch origin gh-pages + git checkout gh-pages + cp /tmp/robots.txt robots.txt + cp /tmp/llms.txt llms.txt + cp /tmp/indexnow.txt 0d5d9799b1cc4a39825146388c6781eb.txt + git add robots.txt llms.txt 0d5d9799b1cc4a39825146388c6781eb.txt + git diff --cached --quiet || git commit -m "chore: update GEO root files (robots.txt, llms.txt, indexnow)" + git push origin gh-pages + + - name: 📡 Notify IndexNow + if: > + (github.event_name == 'push' && github.ref == 'refs/heads/develop') || + github.event_name == 'workflow_dispatch' || + (github.event_name == 'release' && github.event.action == 'published') + run: | + curl -s -o /dev/null -w "%{http_code}" -X POST "https://api.indexnow.org/IndexNow" \ + -H "Content-Type: application/json; charset=utf-8" \ + -d '{ + "host": "supervision.roboflow.com", + "key": "0d5d9799b1cc4a39825146388c6781eb", + "keyLocation": "https://supervision.roboflow.com/0d5d9799b1cc4a39825146388c6781eb.txt", + "urlList": [ + "https://supervision.roboflow.com/", + "https://supervision.roboflow.com/latest/", + "https://supervision.roboflow.com/latest/how_to/detect_and_annotate/", + "https://supervision.roboflow.com/latest/how_to/track_objects/", + "https://supervision.roboflow.com/latest/how_to/detect_small_objects/", + "https://supervision.roboflow.com/latest/how_to/filter_detections/", + "https://supervision.roboflow.com/latest/how_to/save_detections/", + "https://supervision.roboflow.com/latest/how_to/count_in_zone/", + "https://supervision.roboflow.com/latest/how_to/benchmark_a_model/", + "https://supervision.roboflow.com/latest/how_to/process_datasets/" + ] + }' || true diff --git a/docs/0d5d9799b1cc4a39825146388c6781eb.txt b/docs/0d5d9799b1cc4a39825146388c6781eb.txt new file mode 100644 index 00000000..4c8cc29a --- /dev/null +++ b/docs/0d5d9799b1cc4a39825146388c6781eb.txt @@ -0,0 +1 @@ +0d5d9799b1cc4a39825146388c6781eb diff --git a/docs/changelog.md b/docs/changelog.md index 231c99f3..fa74f1a9 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,3 +1,7 @@ +--- +description: "Full version history of the supervision Python library — release notes, breaking changes, new features, and deprecations for every version." +--- + # Changelog ### 0.28.0 Unreleased diff --git a/docs/datasets/core.md b/docs/datasets/core.md index 73931515..98013280 100644 --- a/docs/datasets/core.md +++ b/docs/datasets/core.md @@ -1,5 +1,6 @@ --- comments: true +description: API reference for supervision's DetectionDataset and ClassificationDataset — load, merge, split, and convert datasets in YOLO, COCO, and VOC formats. --- # Datasets diff --git a/docs/detection/annotators.md b/docs/detection/annotators.md index e6dd21bf..90a9006c 100644 --- a/docs/detection/annotators.md +++ b/docs/detection/annotators.md @@ -1,5 +1,6 @@ --- comments: true +description: API reference for supervision's annotator classes — draw bounding boxes, masks, labels, tracks, and heatmaps on images with one method call. --- # Annotators diff --git a/docs/detection/core.md b/docs/detection/core.md index 35225cec..0b40cd3a 100644 --- a/docs/detection/core.md +++ b/docs/detection/core.md @@ -1,5 +1,6 @@ --- comments: true +description: API reference for supervision's Detections class — the core data structure for bounding boxes, masks, confidence scores, and tracker IDs. --- # Detections diff --git a/docs/how_to/benchmark_a_model.md b/docs/how_to/benchmark_a_model.md index 04b4f8a2..de1266f6 100644 --- a/docs/how_to/benchmark_a_model.md +++ b/docs/how_to/benchmark_a_model.md @@ -1,5 +1,6 @@ --- comments: true +description: Benchmark object detection models with supervision — compute mAP, confusion matrix, and per-class metrics to compare model performance. --- ![Corgi Example](https://media.roboflow.com/supervision/image-examples/how-to/benchmark-models/corgi-sorted-2.png) @@ -74,6 +75,8 @@ This will create a folder called `Corgi-v2-4` with the dataset in the current wo Let's load a model. +Select and instantiate the detection or segmentation model you want to benchmark. Supervision works with Roboflow Inference for both local and cloud-deployed models, as well as Ultralytics YOLO checkpoints. Choose the tab below that matches your preferred framework, then pass images to the loaded model during the evaluation loop. + === "Inference, Local" Roboflow supports a range of state-of-the-art [pre-trained models](https://inference.roboflow.com/quickstart/aliases/) for object detection, instance segmentation, and pose tracking. You don't even need an API key! diff --git a/docs/how_to/count_in_zone.md b/docs/how_to/count_in_zone.md index 01ddfab1..0980ff46 100644 --- a/docs/how_to/count_in_zone.md +++ b/docs/how_to/count_in_zone.md @@ -1,3 +1,8 @@ +--- +comments: true +description: Count objects entering a polygon zone in images and video using supervision's PolygonZone — measure throughput and density in any region. +--- + With supervision, you can count the number of objects in a zone in an image or video. In this guide, we will show how to count the number of cars in a traffic video. [View the notebook that accompanies this tutorial](https://github.com/roboflow/notebooks/blob/main/notebooks/how-to-use-polygonzone-annotate-and-supervision.ipynb). @@ -14,6 +19,8 @@ download_assets(VideoAssets.VEHICLES_2) First, we need to initialize a model. Let's use a YOLOv8 model with the default COCO checkpoint. We also need to load a video on which to run inference. +Create a YOLO model instance and load the source video using supervision's `VideoInfo` helper. The model will process each frame during inference, while `VideoInfo` extracts resolution and frame-rate metadata needed by the polygon zone annotator. A shared color palette ensures consistent zone coloring throughout the output video. + ```python import numpy as np import supervision as sv @@ -65,6 +72,8 @@ polygons = [ With the coordinates of the zones to draw ready, we can set up our zones: +Instantiate a `PolygonZone` for each polygon array, pairing it with a `PolygonZoneAnnotator` for visual overlay and a `BoxAnnotator` for drawing detection boxes. Each zone will later trigger on incoming detections to determine which objects fall inside its boundaries, enabling per-zone counting in the inference callback. + ```python zones = [ sv.PolygonZone(polygon=polygon, frame_resolution_wh=video_info.resolution_wh) diff --git a/docs/how_to/detect_and_annotate.md b/docs/how_to/detect_and_annotate.md index c1c48f3d..e998eac1 100644 --- a/docs/how_to/detect_and_annotate.md +++ b/docs/how_to/detect_and_annotate.md @@ -1,5 +1,6 @@ --- comments: true +description: Learn to load model predictions, create Detections objects, and annotate images with bounding boxes, labels, and masks using supervision. --- # Detect and Annotate @@ -19,6 +20,8 @@ source image. First, you'll need to obtain predictions from your object detection or segmentation model. +To run inference, initialize your chosen model and pass the source image to its predict or infer method. Supervision supports Roboflow Inference, Ultralytics YOLO, and Hugging Face Transformers -- select the tab matching your framework. The result is a framework-specific object you will convert to a `Detections` instance in the next step. + === "Inference" ```python @@ -68,6 +71,8 @@ model. Now that we have predictions from a model, we can load them into Supervision. +Each supported framework has a dedicated class method on `sv.Detections` that converts raw model output into a unified Supervision object. Call `from_inference`, `from_ultralytics`, or `from_transformers` depending on the package you used for inference. This normalization step ensures all downstream annotators and filters work identically regardless of the source model. + === "Inference" We can do so using the [`sv.Detections.from_inference`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_inference) method, which accepts model results from both detection and segmentation models. @@ -138,6 +143,8 @@ You can load predictions from other computer vision frameworks and libraries usi Finally, we can annotate the image with the predictions. Since we are working with an object detection model, we will use the [`sv.BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) and [`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator) classes. +To draw bounding boxes and class labels on your image, create a `BoxAnnotator` and a `LabelAnnotator`, then call their `annotate` methods in sequence. Each annotator returns the modified image, so you can chain multiple annotators together. The result is a single NumPy array with all visual overlays rendered and ready for display or saving. + === "Inference" ```{ .py hl_lines="10-16" } diff --git a/docs/how_to/detect_small_objects.md b/docs/how_to/detect_small_objects.md index e4cb7a32..3d68dd0e 100644 --- a/docs/how_to/detect_small_objects.md +++ b/docs/how_to/detect_small_objects.md @@ -1,5 +1,6 @@ --- comments: true +description: Detect small objects in images by applying SAHI inference slicing with supervision's InferenceSlicer — improve recall for tiny targets. --- # Detect Small Objects @@ -19,6 +20,8 @@ with the [Inference](https://github.com/roboflow/inference), Small object detection in high-resolution images presents challenges due to the objects' size relative to the image resolution. +Running a standard detection model on the full image establishes a baseline for comparison. Load your chosen model, pass the image through it, and convert the results into a `Detections` object. This baseline reveals how many small objects the model misses at native resolution, motivating the sliced inference approach shown later. + === "Inference" ```python diff --git a/docs/how_to/filter_detections.md b/docs/how_to/filter_detections.md index 64e26618..14d8d3e3 100644 --- a/docs/how_to/filter_detections.md +++ b/docs/how_to/filter_detections.md @@ -1,5 +1,6 @@ --- comments: true +description: Filter and query detection results by class, confidence, or spatial overlap using supervision's Detections API — clean predictions in one line. --- # Filter Detections diff --git a/docs/how_to/process_datasets.md b/docs/how_to/process_datasets.md index f752be33..b6aa8a0b 100644 --- a/docs/how_to/process_datasets.md +++ b/docs/how_to/process_datasets.md @@ -1,5 +1,6 @@ --- comments: true +description: Load, split, merge, and convert computer vision datasets between YOLO, COCO, and Pascal VOC formats using supervision's DetectionDataset. --- With Supervision, you can load and manipulate classification, object detection, and diff --git a/docs/how_to/save_detections.md b/docs/how_to/save_detections.md index bda4790f..10f094a4 100644 --- a/docs/how_to/save_detections.md +++ b/docs/how_to/save_detections.md @@ -1,5 +1,6 @@ --- comments: true +description: Save object detection results to CSV or JSON with supervision's CSVSink and JSONSink — export predictions for analysis and downstream pipelines. --- # Save Detections @@ -18,6 +19,8 @@ First, you'll need to obtain predictions from your object detection or segmentat model. You can learn more on this topic in our [How to Detect and Annotate](https://supervision.roboflow.com/latest/how_to/detect_and_annotate/) guide. +To generate predictions for saving, initialize your model and iterate over video frames using `sv.get_video_frames_generator`. Each frame is passed to the model, and the raw output is converted into a `sv.Detections` object. This detection loop forms the foundation for both CSV and JSON export workflows shown below. + === "Inference" ```python diff --git a/docs/how_to/track_objects.md b/docs/how_to/track_objects.md index 8cf9eae0..6ac6174e 100644 --- a/docs/how_to/track_objects.md +++ b/docs/how_to/track_objects.md @@ -1,5 +1,6 @@ --- comments: true +description: Track objects across video frames with ByteTrack in supervision — assign persistent IDs and analyze motion from any object detection model. --- # Track Objects @@ -19,6 +20,8 @@ To make it easier for you to follow our tutorial download the video we will use example. You can do this using [`supervision[assets]`](https://supervision.roboflow.com/latest/assets/) extension. +This section demonstrates how to detect and segment objects in video frames using YOLOv8 with either the Inference or Ultralytics package. You will download a sample video, define a per-frame callback function that runs model prediction, and process the entire video to produce an annotated output file. + ```python from supervision.assets import download_assets, VideoAssets diff --git a/docs/index.md b/docs/index.md index 251ec767..e3f9c0ea 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,7 @@ comments: true hide: - navigation - toc +description: Open-source Python library providing computer vision tools for annotating detections, tracking objects, counting in zones, and processing datasets. ---
@@ -23,6 +24,14 @@ hide: } +## What is Supervision? + +Supervision is an open-source Python library by Roboflow for building computer vision applications. It provides a unified `Detections` object that works with YOLO, SAM, Grounding DINO, Transformers, and 20+ model frameworks — use any detector, get the same composable API. + +With Supervision you can annotate images and video with bounding boxes, masks, and labels; track objects across frames with persistent IDs; count and filter detections inside polygon zones; load and convert datasets between YOLO, COCO, and Pascal VOC formats; and benchmark model performance with mAP and confusion matrices. + +Trusted by researchers (cited in 4,000+ papers) and practitioners (38,000+ GitHub stars, 1M+ monthly PyPI downloads), Supervision is the standard toolkit for production computer vision workflows. + ## 👋 Hello We write your reusable computer vision tools. Whether you need to load your dataset from your hard drive, draw detections on an image or video, or count how many detections are in a zone. You can count on us! diff --git a/docs/llms.txt b/docs/llms.txt new file mode 100644 index 00000000..e559755e --- /dev/null +++ b/docs/llms.txt @@ -0,0 +1,59 @@ +# supervision + +> Open-source Python library for computer vision — annotate, track, count, filter, and convert. + +Supervision is a Python library by Roboflow that provides a model-agnostic `Detections` class and composable tools for object detection and segmentation workflows. Works with YOLO, SAM, Grounding DINO, Transformers, Inference, and 20+ other model frameworks. + +## Install + +``` +pip install supervision +``` + +## Links + +- GitHub: https://github.com/roboflow/supervision +- PyPI: https://pypi.org/project/supervision +- Docs: https://supervision.roboflow.com/latest/ +- Changelog: https://supervision.roboflow.com/latest/changelog/ + +## Key APIs + +- `sv.Detections` — core data structure for bounding boxes, masks, confidence scores, class IDs, and tracker IDs +- `sv.BoxAnnotator`, `sv.MaskAnnotator`, `sv.LabelAnnotator` — draw predictions on images and video +- `sv.ByteTrack`, `sv.SORT` — track objects across video frames with persistent IDs +- `sv.PolygonZone`, `sv.LineZone` — count and filter detections by spatial region +- `sv.DetectionDataset` — load, merge, split, and convert YOLO / COCO / Pascal VOC datasets +- `sv.InferenceSlicer` — SAHI-style sliced inference for small object detection +- `sv.CSVSink`, `sv.JSONSink` — export detection results to CSV or JSON + +## How-To Guides + +- Detect and annotate: https://supervision.roboflow.com/latest/how_to/detect_and_annotate/ +- Track objects: https://supervision.roboflow.com/latest/how_to/track_objects/ +- Detect small objects: https://supervision.roboflow.com/latest/how_to/detect_small_objects/ +- Filter detections: https://supervision.roboflow.com/latest/how_to/filter_detections/ +- Save detections: https://supervision.roboflow.com/latest/how_to/save_detections/ +- Count in zone: https://supervision.roboflow.com/latest/how_to/count_in_zone/ +- Benchmark a model: https://supervision.roboflow.com/latest/how_to/benchmark_a_model/ +- Process datasets: https://supervision.roboflow.com/latest/how_to/process_datasets/ + +## License + +MIT — https://github.com/roboflow/supervision/blob/develop/LICENSE.md + +## Citation + +```bibtex +@software{supervision, + author = {Roboflow}, + title = {Supervision: Computer Vision Toolkit}, + url = {https://github.com/roboflow/supervision}, + year = {2023} +} +``` + +## Versioning + +Stable release docs: https://supervision.roboflow.com/latest/ +Development branch: https://supervision.roboflow.com/develop/ diff --git a/docs/robots.txt b/docs/robots.txt new file mode 100644 index 00000000..a84519f7 --- /dev/null +++ b/docs/robots.txt @@ -0,0 +1,34 @@ +User-agent: * +Allow: / +# Block all numeric versioned paths (/0.28.0/, /1.0.0/, etc.) — canonical URL is /latest/ +# robots.txt has no character classes, so one Disallow per leading digit is required. +Disallow: /0.*/ +Disallow: /1.*/ +Disallow: /2.*/ +Disallow: /3.*/ +Disallow: /4.*/ +Disallow: /5.*/ +Disallow: /6.*/ +Disallow: /7.*/ +Disallow: /8.*/ +Disallow: /9.*/ + +User-agent: GPTBot +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: Bytespider +Allow: / + +User-agent: CCBot +Allow: / + +User-agent: GoogleOther +Allow: / + +Sitemap: https://supervision.roboflow.com/sitemap.xml diff --git a/docs/theme/main.html b/docs/theme/main.html index a19af310..c574a2e9 100644 --- a/docs/theme/main.html +++ b/docs/theme/main.html @@ -13,6 +13,163 @@ {% block extrahead %} {{ super() }} + +{# ── GEO: JSON-LD + OG tags (page context required — skip for theme templates like 404) #} +{% if page %} + +{# ── GEO: JSON-LD structured data ───────────────────────────────────────── #} + + +{% if page.is_homepage %} + + + +{% endif %} + +{% if 'how_to' in page.url %} + +{% endif %} + +{% if not page.is_homepage %} + +{% endif %} + +{# ── GEO: Open Graph + Twitter Card meta tags ────────────────────────────── #} + + + + + + + + + + + +{# IndexNow ownership key — do NOT change this value. + The same key must exist in three places (all must stay in sync): + 1. This meta tag (docs/theme/main.html) + 2. The key file at docs/0d5d9799b1cc4a39825146388c6781eb.txt + 3. The CI step in .github/workflows/publish-docs.yml + Bing/Yandex verify ownership by fetching https://supervision.roboflow.com/.txt + and comparing its contents to this meta tag before accepting IndexNow submissions. #} + + +{% endif %} + {% endblock %} diff --git a/docs/trackers.md b/docs/trackers.md index cb44441f..657af015 100644 --- a/docs/trackers.md +++ b/docs/trackers.md @@ -1,5 +1,6 @@ --- comments: true +description: API reference for supervision's object trackers — ByteTrack and SORT implementations that assign persistent IDs across video frames. --- # ByteTrack diff --git a/mkdocs.yml b/mkdocs.yml index cf6789d9..f87f90b0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,7 @@ site_name: Supervision site_url: https://supervision.roboflow.com/ site_author: Roboflow -site_description: A set of easy-to-use utilities that will come in handy in any computer vision project. +site_description: "Model-agnostic Python library for computer vision. Annotate, track, filter, and export detections. Works with YOLO, SAM, Transformers, and 20+ frameworks." repo_name: roboflow/supervision edit_uri: https://github.com/roboflow/supervision/tree/main/docs copyright: Roboflow 2025. All rights reserved.