diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index f1c65fa6..a96bf1ac 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -74,14 +74,16 @@ jobs: run: | cp docs/robots.txt /tmp/robots.txt cp docs/llms.txt /tmp/llms.txt + cp docs/llms.full.txt /tmp/llms.full.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/llms.full.txt llms.full.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 add robots.txt llms.txt llms.full.txt 0d5d9799b1cc4a39825146388c6781eb.txt + git diff --cached --quiet || git commit -m "chore: update GEO root files (robots.txt, llms.txt, llms.full.txt, indexnow)" git push origin gh-pages - name: πŸ“‘ Notify IndexNow diff --git a/docs/assets.md b/docs/assets.md index 7780b903..691ba7e4 100644 --- a/docs/assets.md +++ b/docs/assets.md @@ -1,5 +1,6 @@ --- comments: true +description: API reference for supervision's assets module β€” download sample video and image files for demos, testing, and tutorials. --- # Assets diff --git a/docs/changelog.md b/docs/changelog.md index fa74f1a9..f3c31f4d 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,5 +1,6 @@ --- description: "Full version history of the supervision Python library β€” release notes, breaking changes, new features, and deprecations for every version." +date_modified: 2026-04-23 --- # Changelog diff --git a/docs/cookbooks.md b/docs/cookbooks.md index 6f87958f..5d0d13a8 100644 --- a/docs/cookbooks.md +++ b/docs/cookbooks.md @@ -1,6 +1,7 @@ --- template: cookbooks.html comments: true +description: Collection of practical computer vision cookbooks β€” object tracking, zero-shot detection, SAHI small object detection, occupancy analytics, and more. hide: - navigation - toc diff --git a/docs/how_to/benchmark_a_model.md b/docs/how_to/benchmark_a_model.md index de1266f6..f2988fa1 100644 --- a/docs/how_to/benchmark_a_model.md +++ b/docs/how_to/benchmark_a_model.md @@ -1,6 +1,11 @@ --- comments: true description: Benchmark object detection models with supervision β€” compute mAP, confusion matrix, and per-class metrics to compare model performance. +authors: + - name: SkalskiP (Piotr Skalski) + role: Computer Vision Engineer, Roboflow + github: https://github.com/SkalskiP +date_modified: 2026-04-22 --- ![Corgi Example](https://media.roboflow.com/supervision/image-examples/how-to/benchmark-models/corgi-sorted-2.png) @@ -445,3 +450,25 @@ A condensed version of this guide is also available as a [Colab Notebook](https: For more details, be sure to check out our [documentation](https://supervision.roboflow.com/latest/) and join our community discussions. If you find any issues, please let us know on [GitHub](https://github.com/roboflow/supervision/issues). Best of luck with your benchmarking! + +## Frequently Asked Questions + +### How do I benchmark a model with supervision? + +Use `supervision.metrics.mean_average_precision.MeanAveragePrecision` β€” accumulate prediction and ground-truth `Detections` with `update(...)` and then call `compute()`. For confusion matrices, use `sv.ConfusionMatrix.from_detections(predictions=predictions, targets=targets, classes=classes)`. + +### What IoU thresholds does MeanAveragePrecision use? + +It computes mAP over IoU thresholds from 0.50 to 0.95 in steps of 0.05 (mAP@50:95), plus mAP@50 and mAP@75 individually. + +### Can I benchmark segmentation models? + +Yes, if you want to evaluate their bounding boxes. Convert model outputs to `Detections` and pass them to `MeanAveragePrecision.update(...)`; the current mAP path prepares COCO-style bounding boxes from `detections.xyxy`. + +### What is a ConfusionMatrix and how do I use it? + +`sv.ConfusionMatrix` visualizes true positives, false positives, and false negatives per class. Create one with `sv.ConfusionMatrix.from_detections(predictions=predictions, targets=targets, classes=classes, conf_threshold=0.5, iou_threshold=0.5)`, then call `metric.plot()` to render a heatmap. + +## Author + +- [Piotr Skalski](https://github.com/SkalskiP) β€” Computer Vision Engineer, Roboflow diff --git a/docs/how_to/count_in_zone.md b/docs/how_to/count_in_zone.md index 0980ff46..0788b154 100644 --- a/docs/how_to/count_in_zone.md +++ b/docs/how_to/count_in_zone.md @@ -1,6 +1,11 @@ --- comments: true description: Count objects entering a polygon zone in images and video using supervision's PolygonZone β€” measure throughput and density in any region. +authors: + - name: SkalskiP (Piotr Skalski) + role: Computer Vision Engineer, Roboflow + github: https://github.com/SkalskiP +date_modified: 2026-04-22 --- 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. @@ -132,3 +137,21 @@ Here is an example of inference run on the video: + +## Frequently Asked Questions + +### How do I count objects in a zone with supervision? + +Create `sv.PolygonZone` with a polygon defining your region. Call `zone.trigger(detections)` on each frame β€” it returns a mask of detections inside the zone. + +### Can I count objects crossing a line instead of entering a zone? + +Yes. Use `sv.LineZone` β€” define a start and end point. `zone.trigger(detections)` returns a tuple of two boolean arrays, `(crossed_in, crossed_out)`, indicating which detections crossed the line in each direction. `LineZone` requires `detections.tracker_id`; run a tracker first so the same object can be matched across frames. + +### Can I combine zone counting with tracking? + +Yes. You can pass tracker IDs from `sv.ByteTrack` alongside your detections, but `sv.PolygonZone` still evaluates the zone on each frame and reports which objects are currently inside it. If you want to count each object only once when it first enters the zone, maintain a set of seen `tracker_id` values after filtering detections with `zone.trigger(detections)`, or use a dedicated entry/crossing counting tool such as `sv.LineZone` when it better matches your use case. + +## Author + +- [Piotr Skalski](https://github.com/SkalskiP) β€” Computer Vision Engineer, Roboflow diff --git a/docs/how_to/detect_and_annotate.md b/docs/how_to/detect_and_annotate.md index e998eac1..09e3bc33 100644 --- a/docs/how_to/detect_and_annotate.md +++ b/docs/how_to/detect_and_annotate.md @@ -1,6 +1,14 @@ --- comments: true description: Learn to load model predictions, create Detections objects, and annotate images with bounding boxes, labels, and masks using supervision. +authors: + - name: SkalskiP (Piotr Skalski) + role: Computer Vision Engineer, Roboflow + github: https://github.com/SkalskiP + - name: Borda + role: Open Source Engineer, Roboflow + github: https://github.com/borda +date_modified: 2026-04-22 --- # Detect and Annotate @@ -427,3 +435,26 @@ that will allow you to draw masks instead of boxes. ``` ![segmentation-annotation](https://media.roboflow.com/supervision_detect_and_annotate_example_3.png) + +## Frequently Asked Questions + +### How do I detect and annotate objects with supervision? + +Pass any model's output to `sv.Detections.from_()` to create a unified `Detections` object. Then pass it to `sv.BoxAnnotator` or `sv.MaskAnnotator` to draw predictions on an image. + +### Can I annotate both bounding boxes and masks at the same time? + +Yes. Chain annotators: first draw boxes with `BoxAnnotator`, then overlay masks with `MaskAnnotator` on the same scene. + +### How do I label detections with class names? + +Use `sv.LabelAnnotator` and pass custom text with the `labels` parameter. If a connector provides class names, they are stored in `detections["class_name"]` / `detections.data["class_name"]`; when `labels` is omitted, `LabelAnnotator` uses class names first, then class IDs, then detection indices. + +### Can I use supervision with Hugging Face models? + +Yes. `sv.Detections.from_transformers()` accepts supported Hugging Face object detection and segmentation outputs. Vision-language model outputs are handled through `sv.Detections.from_vlm(...)`, for example with `sv.VLM.FLORENCE_2` or `sv.VLM.PALIGEMMA`. + +## Authors + +- [Piotr Skalski](https://github.com/SkalskiP) β€” Computer Vision Engineer, Roboflow +- [Borda](https://github.com/borda) β€” Open Source Engineer, Roboflow diff --git a/docs/how_to/detect_small_objects.md b/docs/how_to/detect_small_objects.md index 3d68dd0e..2e204bb8 100644 --- a/docs/how_to/detect_small_objects.md +++ b/docs/how_to/detect_small_objects.md @@ -1,6 +1,11 @@ --- comments: true description: Detect small objects in images by applying SAHI inference slicing with supervision's InferenceSlicer β€” improve recall for tiny targets. +authors: + - name: SkalskiP (Piotr Skalski) + role: Computer Vision Engineer, Roboflow + github: https://github.com/SkalskiP +date_modified: 2026-04-22 --- # Detect Small Objects @@ -331,3 +336,21 @@ objects within each, and aggregating the results. ``` ![detection-with-inference-slicer](https://media.roboflow.com/supervision-docs/inference-slicer-segmentation-example.png) + +## Frequently Asked Questions + +### How do I detect small objects with supervision? + +Use `sv.InferenceSlicer` to split a high-resolution image into overlapping tiles, run detection on each tile, and merge results with non-maximum suppression. This dramatically improves recall for tiny targets. + +### What overlap should I use between tiles? + +`InferenceSlicer` takes overlap in pixels via `overlap_wh`, not as a percentage. The default is `100` pixels in both directions. Increase `overlap_wh` when objects are close to the tile size or often appear on tile boundaries, and decrease it when speed is more important. + +### Can I use InferenceSlicer with any detection model? + +Yes. Wrap any model that can produce `sv.Detections` (from YOLO, SAM, Grounding DINO, Transformers, etc.) in a callback, pass that callback to `sv.InferenceSlicer(callback=...)`, and then call the slicer with your image. + +## Author + +- [Piotr Skalski](https://github.com/SkalskiP) β€” Computer Vision Engineer, Roboflow diff --git a/docs/how_to/filter_detections.md b/docs/how_to/filter_detections.md index 14d8d3e3..89f85573 100644 --- a/docs/how_to/filter_detections.md +++ b/docs/how_to/filter_detections.md @@ -1,6 +1,11 @@ --- comments: true description: Filter and query detection results by class, confidence, or spatial overlap using supervision's Detections API β€” clean predictions in one line. +authors: + - name: SkalskiP (Piotr Skalski) + role: Computer Vision Engineer, Roboflow + github: https://github.com/SkalskiP +date_modified: 2026-04-22 --- # Filter Detections @@ -313,3 +318,29 @@ zone. In the example below you can see how to filter out all detections located ![original](https://media.roboflow.com/open-source/supervision/supervision-detection-original.png){ align=center width="800" } + +## Frequently Asked Questions + +### How do I filter detections by class in supervision? + +Use NumPy-style boolean indexing: `detections[detections.class_id == 0]` for class 0. Combine with `&` or `|` for multiple conditions. + +### How do I filter by confidence threshold? + +`detections[detections.confidence > 0.5]` returns only detections above the threshold. Chain with class filters for precise results. + +### How do I filter by bounding box area? + +`detections[detections.area > 1000]` filters by pixel area. If masks are present, `detections.area` uses mask area; otherwise it uses bounding box area from `xyxy`. Use `detections.box_area` when you specifically need bounding box area. + +### Can I filter by box aspect ratio or dimensions? + +Yes. Use `detections.box_aspect_ratio` for aspect ratio filtering. If you need explicit box dimensions, compute them from `detections.xyxy` as `width = detections.xyxy[:, 2] - detections.xyxy[:, 0]` and `height = detections.xyxy[:, 3] - detections.xyxy[:, 1]`. + +### How do I remove duplicate detections (NMS) from my results? + +Use `detections.with_nms(threshold=0.5)` β€” it applies non-maximum suppression on the `xyxy` boxes. + +## Author + +- [Piotr Skalski](https://github.com/SkalskiP) β€” Computer Vision Engineer, Roboflow diff --git a/docs/how_to/process_datasets.md b/docs/how_to/process_datasets.md index b6aa8a0b..39a4a542 100644 --- a/docs/how_to/process_datasets.md +++ b/docs/how_to/process_datasets.md @@ -1,6 +1,11 @@ --- comments: true description: Load, split, merge, and convert computer vision datasets between YOLO, COCO, and Pascal VOC formats using supervision's DetectionDataset. +authors: + - name: SkalskiP (Piotr Skalski) + role: Computer Vision Engineer, Roboflow + github: https://github.com/SkalskiP +date_modified: 2026-04-22 --- With Supervision, you can load and manipulate classification, object detection, and @@ -450,3 +455,25 @@ augmented_annotations = replace( ``` ![augment-dataset](https://media.roboflow.com/supervision-docs/augment-dataset.png) + +## Frequently Asked Questions + +### What dataset formats does supervision support? + +For detection datasets, supervision supports YOLO, COCO JSON, and Pascal VOC. Use `DetectionDataset.from_yolo()`, `from_coco()`, or `from_pascal_voc()` to load, and `as_yolo()`, `as_coco()`, or `as_pascal_voc()` to save. Classification datasets use `ClassificationDataset.from_folder_structure()` and `as_folder_structure()`. + +### Can I split a dataset into train/val/test sets? + +`DetectionDataset.split(split_ratio=0.8)` returns exactly two datasets: train (80%) and test (20%). If you need a validation set, split one of those subsets in a separate step. + +### Can I merge two datasets together? + +Yes. `DetectionDataset.merge([dataset_a, dataset_b])` combines multiple datasets into one. Useful for combining datasets from different sources. + +### What augmentations are available? + +Common augmentations such as flip, rotate, translate, scale, crop, color jitter, and Gaussian blur can be applied using an external library like Albumentations, as shown in the augmentation example above. Supervision does not provide an `sv.Augmenter` pipeline. + +## Author + +- [Piotr Skalski](https://github.com/SkalskiP) β€” Computer Vision Engineer, Roboflow diff --git a/docs/how_to/save_detections.md b/docs/how_to/save_detections.md index 10f094a4..b2f659eb 100644 --- a/docs/how_to/save_detections.md +++ b/docs/how_to/save_detections.md @@ -1,6 +1,11 @@ --- comments: true description: Save object detection results to CSV or JSON with supervision's CSVSink and JSONSink β€” export predictions for analysis and downstream pipelines. +authors: + - name: SkalskiP (Piotr Skalski) + role: Computer Vision Engineer, Roboflow + github: https://github.com/SkalskiP +date_modified: 2026-04-22 --- # Save Detections @@ -11,7 +16,7 @@ processing. This guide demonstrates how to perform video inference using the [Ultralytics](https://github.com/ultralytics/ultralytics) or [Transformers](https://github.com/huggingface/transformers) packages and save their results with [`sv.CSVSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink) and -[`sv.JSONSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.JSONSink). +[`sv.JSONSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.json_sink.JSONSink). ## Run Detection @@ -234,7 +239,7 @@ If you prefer to save the result in a `.JSON` file instead of a `.CSV` file, all need to do is replace [`sv.CSVSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink) with -[`sv.JSONSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.JSONSink). +[`sv.JSONSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.json_sink.JSONSink). === "Inference" @@ -297,3 +302,25 @@ with detections = sv.Detections.from_transformers(results) sink.append(detections, {"frame_index": frame_index}) ``` + +## Frequently Asked Questions + +### How do I save detections to CSV with supervision? + +Open `sv.CSVSink("output.csv")` as a context manager and call `sink.append(detections)` for each frame. The CSV includes box coordinates, confidence, class ID, tracker ID, and any fields stored in `detections.data`. + +### Can I save detections to JSON instead? + +Yes. Open `sv.JSONSink("output.json")` as a context manager and call `sink.append(detections)` for each frame. The file is written as a JSON array when the context exits. + +### Can I add custom fields to the saved output? + +Yes. Pass a dict as the second argument: `sink.append(detections, {"frame_index": 5})` β€” the keys become extra columns in the CSV or extra fields in the JSON. + +### Can I save only specific classes or confidence levels? + +Filter the `Detections` object before saving: `sink.append(detections[detections.confidence > 0.7])`. + +## Author + +- [Piotr Skalski](https://github.com/SkalskiP) β€” Computer Vision Engineer, Roboflow diff --git a/docs/how_to/track_objects.md b/docs/how_to/track_objects.md index 6ac6174e..f2bec977 100644 --- a/docs/how_to/track_objects.md +++ b/docs/how_to/track_objects.md @@ -1,6 +1,14 @@ --- comments: true description: Track objects across video frames with ByteTrack in supervision β€” assign persistent IDs and analyze motion from any object detection model. +authors: + - name: SkalskiP (Piotr Skalski) + role: Computer Vision Engineer, Roboflow + github: https://github.com/SkalskiP + - name: soumik12345 (Soumik Mandal) + role: ML Engineer, Roboflow + github: https://github.com/soumik12345 +date_modified: 2026-04-22 --- # Track Objects @@ -656,3 +664,26 @@ We could stop here as we have successfully tracked the object detected by the ke This structured walkthrough should give a detailed pathway to annotate videos effectively using Supervision’s various functionalities, including object tracking and trace annotations. + +## Frequently Asked Questions + +### How do I track objects across video frames with supervision? + +Pass `Detections` to `sv.ByteTrack.update_with_detections()` on each frame. The tracker assigns persistent IDs. Combine with `sv.TraceAnnotator` to visualize trajectories. `sv.ByteTrack` is deprecated in favor of `ByteTrackTracker` from the `trackers` package, where the update method is named `update()`. + +### What should I know about ByteTrack? + +ByteTrack uses low-confidence detections during association, which can improve continuity during missed or weak detections. Supervision's built-in `ByteTrack` wrapper is deprecated in favor of the external `trackers` package. + +### Can I track instances instead of bounding boxes? + +Yes. ByteTrack tracks bounding boxes. For instance masks, use `sv.MaskAnnotator` with the tracker IDs to color-code each tracked object consistently. + +### Does ByteTrack work with any detection model? + +Yes. ByteTrack is model-agnostic β€” it accepts any `Detections` object with bounding boxes, regardless of source (YOLO, SAM, Grounding DINO, Transformers, etc.). + +## Authors + +- [Piotr Skalski](https://github.com/SkalskiP) β€” Computer Vision Engineer, Roboflow +- [Soumik Mandal](https://github.com/soumik12345) β€” ML Engineer, Roboflow diff --git a/docs/llms.full.txt b/docs/llms.full.txt new file mode 100644 index 00000000..71b22b41 --- /dev/null +++ b/docs/llms.full.txt @@ -0,0 +1,188 @@ +# 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. + +Trusted by researchers in 4,000+ papers and 38,000+ developers. MIT licensed. + +## AI Access + +All major AI crawlers are explicitly allowed. Full documentation is open for AI consumption. + +- GPTBot: allowed +- ClaudeBot: allowed +- PerplexityBot: allowed +- CCBot: allowed +- GoogleOther: allowed + +## Install + +```bash +pip install supervision +``` + +Extras: `pip install supervision[metrics]` for mAP/confusion matrix. `pip install supervision[assets]` for sample video/image assets. + +## Links + +- GitHub: https://github.com/roboflow/supervision +- PyPI: https://pypi.org/project/supervision +- Docs (latest stable): https://supervision.roboflow.com/latest/ +- Docs (develop): https://supervision.roboflow.com/develop/ +- Changelog: https://supervision.roboflow.com/latest/changelog/ +- Sitemap: https://supervision.roboflow.com/sitemap.xml + +## Key APIs + +### sv.Detections + +Core data structure for bounding boxes, masks, confidence scores, class IDs, tracker IDs, and arbitrary per-detection metadata stored in a `data` dict. The lingua franca of the entire library β€” every connector, annotator, and tracker accepts or returns `Detections`. Supports NumPy-style boolean indexing for filtering by class, confidence, area, and spatial regions. + +### sv.BoxAnnotator, sv.MaskAnnotator, sv.LabelAnnotator + +Draw bounding boxes, segmentation masks, and text labels on images. Annotators expose `annotate(scene=..., detections=...)`; pass an input image and a `Detections` object to get the annotated output. `LabelAnnotator` can use explicit `labels` or fall back to `detections["class_name"]`, class IDs, then detection indices. Colors can be assigned by class or manually specified. + +### sv.ByteTrack + +Object tracker wrapper that assigns persistent IDs across video frames. The built-in `sv.ByteTrack` accepts `Detections` via `update_with_detections()`, but it is deprecated in favor of `ByteTrackTracker` from the external `trackers` package, where the method is named `update()`. Use tracked `Detections` with `sv.TraceAnnotator` to visualize trajectories. + +### sv.PolygonZone and sv.LineZone + +Zone-based counting. `PolygonZone.trigger(detections)` returns a boolean mask for detections currently inside an arbitrary polygon. `LineZone.trigger(detections)` returns `(crossed_in, crossed_out)` arrays for line crossings and requires `detections.tracker_id` so objects can be matched across frames. Both are commonly paired with zone annotators for visualization. + +### sv.DetectionDataset and sv.ClassificationDataset + +For detection datasets, load, merge, split, and convert between YOLO, COCO JSON, and Pascal VOC formats. Classification datasets use folder-structure import and export via `ClassificationDataset.from_folder_structure()` and `as_folder_structure()`. + +### sv.InferenceSlicer + +SAHI-style inference slicing: split high-resolution images into overlapping tiles, run detection on each tile, merge results with non-maximum suppression or non-maximum merge. Configure tile overlap in pixels with `overlap_wh`. + +### supervision.metrics.MeanAveragePrecision and sv.ConfusionMatrix + +Benchmarking tools. For mAP@0.5:0.95, use `supervision.metrics.MeanAveragePrecision` with `update()` and `compute()` rather than the deprecated top-level `sv.MeanAveragePrecision.from_detections()`. `ConfusionMatrix.from_detections(predictions=predictions, targets=targets, classes=classes)` generates a confusion matrix for detection results. + +### sv.CSVSink and sv.JSONSink + +Export detection results to structured files. Use `CSVSink` and `JSONSink` as context managers, call `sink.append(detections, custom_data=...)`, and they write one row/object per detection with box coordinates, confidence, class ID, tracker ID, and data fields. + +## 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/ + +## Reference Documentation + +- Detections (detection/core): https://supervision.roboflow.com/latest/detection/core/ +- Annotators (detection/annotators): https://supervision.roboflow.com/latest/detection/annotators/ +- CompactMask (detection/compact_mask): https://supervision.roboflow.com/latest/detection/compact_mask/ +- Format Converters (detection/utils/converters): https://supervision.roboflow.com/latest/detection/utils/converters/ +- IoU and NMS (detection/utils/iou_and_nms): https://supervision.roboflow.com/latest/detection/utils/iou_and_nms/ +- Boxes (detection/utils/boxes): https://supervision.roboflow.com/latest/detection/utils/boxes/ +- Masks (detection/utils/masks): https://supervision.roboflow.com/latest/detection/utils/masks/ +- Polygons (detection/utils/polygons): https://supervision.roboflow.com/latest/detection/utils/polygons/ +- VLMs (detection/utils/vlms): https://supervision.roboflow.com/latest/detection/utils/vlms/ +- Keypoint Core (keypoint/core): https://supervision.roboflow.com/latest/keypoint/core/ +- Keypoint Annotators (keypoint/annotators): https://supervision.roboflow.com/latest/keypoint/annotators/ +- Classification Core (classification/core): https://supervision.roboflow.com/latest/classification/core/ +- ByteTrack Tracker (trackers): https://supervision.roboflow.com/latest/trackers/ +- Datasets Core (datasets/core): https://supervision.roboflow.com/latest/datasets/core/ +- mAP (metrics/mean_average_precision): https://supervision.roboflow.com/latest/metrics/mean_average_precision/ +- mAR (metrics/mean_average_recall): https://supervision.roboflow.com/latest/metrics/mean_average_recall/ +- Precision (metrics/precision): https://supervision.roboflow.com/latest/metrics/precision/ +- Recall (metrics/recall): https://supervision.roboflow.com/latest/metrics/recall/ +- F1 Score (metrics/f1_score): https://supervision.roboflow.com/latest/metrics/f1_score/ +- Common Values (metrics/common_values): https://supervision.roboflow.com/latest/metrics/common_values/ +- Line Zone (detection/tools/line_zone): https://supervision.roboflow.com/latest/detection/tools/line_zone/ +- Polygon Zone (detection/tools/polygon_zone): https://supervision.roboflow.com/latest/detection/tools/polygon_zone/ +- Inference Slicer (detection/tools/inference_slicer): https://supervision.roboflow.com/latest/detection/tools/inference_slicer/ +- Detection Smoother (detection/tools/smoother): https://supervision.roboflow.com/latest/detection/tools/smoother/ +- Save Detections Tool (detection/tools/save_detections): https://supervision.roboflow.com/latest/detection/tools/save_detections/ +- Video Utils (utils/video): https://supervision.roboflow.com/latest/utils/video/ +- Image Utils (utils/image): https://supervision.roboflow.com/latest/utils/image/ +- Iterable Utils (utils/iterables): https://supervision.roboflow.com/latest/utils/iterables/ +- Notebook Utils (utils/notebook): https://supervision.roboflow.com/latest/utils/notebook/ +- File Utils (utils/file): https://supervision.roboflow.com/latest/utils/file/ +- Draw Utils (utils/draw): https://supervision.roboflow.com/latest/utils/draw/ +- Geometry (utils/geometry): https://supervision.roboflow.com/latest/utils/geometry/ +- Assets (assets): https://supervision.roboflow.com/latest/assets/ + +## Cookbooks + +- Object tracking: https://supervision.roboflow.com/latest/cookbooks/#object-tracking +- Count objects crossing line: https://supervision.roboflow.com/latest/cookbooks/#count-objects-crossing-the-line +- Zero-shot object detection with YOLO-World: https://supervision.roboflow.com/latest/cookbooks/#zero-shot-object-detection-with-yolo-world +- SAHI small object detection: https://supervision.roboflow.com/latest/cookbooks/#small-object-detection-with-sahi + +## FAQ + +### What is supervision? + +Supervision is an open-source Python library by Roboflow for computer vision workflows. It provides a unified `Detections` class compatible with YOLO, SAM, Grounding DINO, Transformers, and 20+ model frameworks, plus tools for annotation, tracking, zone counting, dataset management, and model benchmarking. + +### How do I install supervision? + +Install with `pip install supervision`. For evaluation tools use `pip install supervision[metrics]`. For sample assets use `pip install supervision[assets]`. The current package metadata requires Python 3.9+. + +### What can I do with supervision? + +Annotate images and video with bounding boxes, masks, and labels; track objects across frames with persistent IDs; count detections inside polygon zones or line crossings; filter and query detection results; load, split, and convert detection datasets between YOLO, COCO, and Pascal VOC formats; manage classification datasets with folder structures; and benchmark model performance with mAP and confusion matrices. + +### Is supervision free to use? + +Yes. Supervision is free and open-source under the MIT license. Source code is at https://github.com/roboflow/supervision. + +### Which object detection models work with supervision? + +Supervision is model-agnostic and works with Ultralytics YOLO, Roboflow Inference, Hugging Face Transformers, SAM, Grounding DINO, Florence-2, PaliGemma, MediaPipe, Detectron2, MMDetection, and 20+ other frameworks through built-in connectors such as `from_ultralytics()`, `from_transformers()`, and `from_vlm(...)`. + +### How do I benchmark a model with supervision? + +Use `supervision.metrics.mean_average_precision.MeanAveragePrecision` for mAP β€” accumulate predictions and ground truth with `update(...)` then call `compute()`. For confusion matrices, use `sv.ConfusionMatrix.from_detections(predictions=predictions, targets=targets, classes=classes)`. See the Benchmark a Model how-to guide for a complete walkthrough. + +### How do I track objects across video frames? + +Use a tracker to assign persistent IDs. The built-in `sv.ByteTrack` wrapper accepts `Detections` with `update_with_detections()`, but it is deprecated in favor of `ByteTrackTracker` from the external `trackers` package. Combine tracked detections with `sv.TraceAnnotator` to visualize trajectories. + +### What dataset formats does supervision support? + +For detection datasets, supervision supports YOLO, COCO JSON, and Pascal VOC. Use `DetectionDataset.from_yolo()`, `from_coco()`, or `from_pascal_voc()` to load, and `as_yolo()`, `as_coco()`, or `as_pascal_voc()` to save. For classification datasets, use `ClassificationDataset.from_folder_structure()` and `as_folder_structure()`. + +### How do I count objects in a zone? + +Use `sv.PolygonZone` for arbitrary polygon zones. Use `sv.LineZone` for line-crossing counts after assigning tracker IDs, because `LineZone` needs `detections.tracker_id` to match objects across frames. + +### How do I detect small objects with supervision? + +Use `sv.InferenceSlicer` to split high-resolution images into overlapping tiles, run detection on each tile, and merge results with non-maximum suppression. Configure tile overlap in pixels with `overlap_wh`. See the Detect Small Objects how-to guide. + +## Benchmarking + +Supervision includes `supervision.metrics.MeanAveragePrecision` and `sv.ConfusionMatrix` for benchmarking object detection models. A curated [Model Leaderboard](https://leaderboard.roboflow.com/) compares YOLOv8, YOLOv11, and other models on standard datasets. The leaderboard repository is open source at https://github.com/roboflow/model-leaderboard. + +## 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/llms.txt b/docs/llms.txt index e559755e..048209ea 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -4,28 +4,59 @@ 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. +Trusted by researchers in 4,000+ papers and 38,000+ developers. MIT licensed. + +## AI Access + +All major AI crawlers are explicitly allowed. Full documentation is open for AI consumption. + +- GPTBot: allowed +- ClaudeBot: allowed +- PerplexityBot: allowed +- CCBot: allowed +- GoogleOther: allowed + ## Install ``` pip install supervision ``` +Extras: `pip install supervision[metrics]` for mAP/confusion matrix. `pip install supervision[assets]` for sample video/image assets. + ## Links - GitHub: https://github.com/roboflow/supervision - PyPI: https://pypi.org/project/supervision -- Docs: https://supervision.roboflow.com/latest/ +- Docs (latest stable): https://supervision.roboflow.com/latest/ - Changelog: https://supervision.roboflow.com/latest/changelog/ +- Sitemap: https://supervision.roboflow.com/sitemap.xml ## 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 +### sv.Detections +Core data structure for bounding boxes, masks, confidence scores, class IDs, tracker IDs, and arbitrary per-detection metadata stored in a `data` dict. The lingua franca of the entire library β€” every connector, annotator, and tracker accepts or returns `Detections`. Supports NumPy-style boolean indexing for filtering by class, confidence, area, and spatial regions. + +### sv.BoxAnnotator, sv.MaskAnnotator, sv.LabelAnnotator +Draw bounding boxes, segmentation masks, and text labels on images. Annotators expose `annotate(scene=..., detections=...)`; pass an input image and a `Detections` object to get the annotated output. `LabelAnnotator` can use explicit `labels` or fall back to `detections["class_name"]`, class IDs, then detection indices. Colors can be assigned by class or manually specified. + +### sv.ByteTrack +Object tracker wrapper that assigns persistent IDs across video frames. The built-in `sv.ByteTrack` accepts `Detections` via `update_with_detections()`, but it is deprecated in favor of `ByteTrackTracker` from the external `trackers` package, where the method is named `update()`. Use tracked `Detections` with `sv.TraceAnnotator` to visualize trajectories. + +### sv.PolygonZone and sv.LineZone +Zone-based counting. `PolygonZone.trigger(detections)` returns a boolean mask for detections currently inside an arbitrary polygon. `LineZone.trigger(detections)` returns `(crossed_in, crossed_out)` arrays for line crossings and requires `detections.tracker_id` so objects can be matched across frames. Both are commonly paired with zone annotators for visualization. + +### sv.DetectionDataset and sv.ClassificationDataset +For detection datasets, load, merge, split, and convert between YOLO, COCO JSON, and Pascal VOC formats. Classification datasets use folder-structure import and export via `ClassificationDataset.from_folder_structure()` and `as_folder_structure()`. + +### sv.InferenceSlicer +SAHI-style inference slicing: split high-resolution images into overlapping tiles, run detection on each tile, merge results with non-maximum suppression or non-maximum merge. Configure tile overlap in pixels with `overlap_wh`. + +### supervision.metrics.MeanAveragePrecision and sv.ConfusionMatrix +Benchmarking tools. For mAP@0.5:0.95, use `supervision.metrics.MeanAveragePrecision` with `update()` and `compute()` rather than the deprecated top-level `sv.MeanAveragePrecision.from_detections()`. `ConfusionMatrix.from_detections(predictions=predictions, targets=targets, classes=classes)` generates a confusion matrix for detection results. + +### sv.CSVSink and sv.JSONSink +Export detection results to structured files. Use `CSVSink` and `JSONSink` as context managers, call `sink.append(detections, custom_data=...)`, and they write one row/object per detection with box coordinates, confidence, class ID, tracker ID, and data fields. ## How-To Guides @@ -38,6 +69,95 @@ pip install supervision - Benchmark a model: https://supervision.roboflow.com/latest/how_to/benchmark_a_model/ - Process datasets: https://supervision.roboflow.com/latest/how_to/process_datasets/ +## Reference Documentation + +- Detections (detection/core): https://supervision.roboflow.com/latest/detection/core/ +- Annotators (detection/annotators): https://supervision.roboflow.com/latest/detection/annotators/ +- CompactMask (detection/compact_mask): https://supervision.roboflow.com/latest/detection/compact_mask/ +- Format Converters (detection/utils/converters): https://supervision.roboflow.com/latest/detection/utils/converters/ +- IoU and NMS (detection/utils/iou_and_nms): https://supervision.roboflow.com/latest/detection/utils/iou_and_nms/ +- Boxes (detection/utils/boxes): https://supervision.roboflow.com/latest/detection/utils/boxes/ +- Masks (detection/utils/masks): https://supervision.roboflow.com/latest/detection/utils/masks/ +- Polygons (detection/utils/polygons): https://supervision.roboflow.com/latest/detection/utils/polygons/ +- VLMs (detection/utils/vlms): https://supervision.roboflow.com/latest/detection/utils/vlms/ +- Keypoint Core (keypoint/core): https://supervision.roboflow.com/latest/keypoint/core/ +- Keypoint Annotators (keypoint/annotators): https://supervision.roboflow.com/latest/keypoint/annotators/ +- Classification Core (classification/core): https://supervision.roboflow.com/latest/classification/core/ +- ByteTrack Tracker (trackers): https://supervision.roboflow.com/latest/trackers/ +- Datasets Core (datasets/core): https://supervision.roboflow.com/latest/datasets/core/ +- mAP (metrics/mean_average_precision): https://supervision.roboflow.com/latest/metrics/mean_average_precision/ +- mAR (metrics/mean_average_recall): https://supervision.roboflow.com/latest/metrics/mean_average_recall/ +- Precision (metrics/precision): https://supervision.roboflow.com/latest/metrics/precision/ +- Recall (metrics/recall): https://supervision.roboflow.com/latest/metrics/recall/ +- F1 Score (metrics/f1_score): https://supervision.roboflow.com/latest/metrics/f1_score/ +- Common Values (metrics/common_values): https://supervision.roboflow.com/latest/metrics/common_values/ +- Line Zone (detection/tools/line_zone): https://supervision.roboflow.com/latest/detection/tools/line_zone/ +- Polygon Zone (detection/tools/polygon_zone): https://supervision.roboflow.com/latest/detection/tools/polygon_zone/ +- Inference Slicer (detection/tools/inference_slicer): https://supervision.roboflow.com/latest/detection/tools/inference_slicer/ +- Detection Smoother (detection/tools/smoother): https://supervision.roboflow.com/latest/detection/tools/smoother/ +- Save Detections Tool (detection/tools/save_detections): https://supervision.roboflow.com/latest/detection/tools/save_detections/ +- Video Utils (utils/video): https://supervision.roboflow.com/latest/utils/video/ +- Image Utils (utils/image): https://supervision.roboflow.com/latest/utils/image/ +- Iterable Utils (utils/iterables): https://supervision.roboflow.com/latest/utils/iterables/ +- Notebook Utils (utils/notebook): https://supervision.roboflow.com/latest/utils/notebook/ +- File Utils (utils/file): https://supervision.roboflow.com/latest/utils/file/ +- Draw Utils (utils/draw): https://supervision.roboflow.com/latest/utils/draw/ +- Geometry (utils/geometry): https://supervision.roboflow.com/latest/utils/geometry/ +- Assets (assets): https://supervision.roboflow.com/latest/assets/ + +## Cookbooks + +- Object tracking: https://supervision.roboflow.com/latest/cookbooks/#object-tracking +- Count objects crossing line: https://supervision.roboflow.com/latest/cookbooks/#count-objects-crossing-the-line +- Zero-shot object detection with YOLO-World: https://supervision.roboflow.com/latest/cookbooks/#zero-shot-object-detection-with-yolo-world +- SAHI small object detection: https://supervision.roboflow.com/latest/cookbooks/#small-object-detection-with-sahi + +## FAQ + +### What is supervision? + +Supervision is an open-source Python library by Roboflow for computer vision workflows. It provides a unified `Detections` class compatible with YOLO, SAM, Grounding DINO, Transformers, and 20+ model frameworks, plus tools for annotation, tracking, zone counting, dataset management, and model benchmarking. + +### How do I install supervision? + +Install with `pip install supervision`. For evaluation tools use `pip install supervision[metrics]`. For sample assets use `pip install supervision[assets]`. The current package metadata requires Python 3.9+. + +### What can I do with supervision? + +Annotate images and video with bounding boxes, masks, and labels; track objects across frames with persistent IDs; count detections inside polygon zones or line crossings; filter and query detection results; load, split, and convert detection datasets between YOLO, COCO, and Pascal VOC formats; manage classification datasets with folder structures; and benchmark model performance with mAP and confusion matrices. + +### Is supervision free to use? + +Yes. Supervision is free and open-source under the MIT license. Source code is at https://github.com/roboflow/supervision. + +### Which object detection models work with supervision? + +Supervision is model-agnostic and works with Ultralytics YOLO, Roboflow Inference, Hugging Face Transformers, SAM, Grounding DINO, Florence-2, PaliGemma, MediaPipe, Detectron2, MMDetection, and 20+ other frameworks through built-in connectors such as `from_ultralytics()`, `from_transformers()`, and `from_vlm(...)`. + +### How do I benchmark a model with supervision? + +Use `supervision.metrics.mean_average_precision.MeanAveragePrecision` for mAP β€” accumulate predictions and ground truth with `update(...)` then call `compute()`. For confusion matrices, use `sv.ConfusionMatrix.from_detections(predictions=predictions, targets=targets, classes=classes)`. See the Benchmark a Model how-to guide for a complete walkthrough. + +### How do I track objects across video frames? + +Use a tracker to assign persistent IDs. The built-in `sv.ByteTrack` wrapper accepts `Detections` with `update_with_detections()`, but it is deprecated in favor of `ByteTrackTracker` from the external `trackers` package. Combine tracked detections with `sv.TraceAnnotator` to visualize trajectories. + +### What dataset formats does supervision support? + +For detection datasets, supervision supports YOLO, COCO JSON, and Pascal VOC. Use `DetectionDataset.from_yolo()`, `from_coco()`, or `from_pascal_voc()` to load, and `as_yolo()`, `as_coco()`, or `as_pascal_voc()` to save. For classification datasets, use `ClassificationDataset.from_folder_structure()` and `as_folder_structure()`. + +### How do I count objects in a zone? + +Use `sv.PolygonZone` for arbitrary polygon zones. Use `sv.LineZone` for line-crossing counts after assigning tracker IDs, because `LineZone` needs `detections.tracker_id` to match objects across frames. + +### How do I detect small objects with supervision? + +Use `sv.InferenceSlicer` to split high-resolution images into overlapping tiles, run detection on each tile, and merge results with non-maximum suppression. Configure tile overlap in pixels with `overlap_wh`. See the Detect Small Objects how-to guide. + +## Benchmarking + +Supervision includes `supervision.metrics.MeanAveragePrecision` and `sv.ConfusionMatrix` for benchmarking object detection models. A curated [Model Leaderboard](https://leaderboard.roboflow.com/) compares YOLOv8, YOLOv11, and other models on standard datasets. The leaderboard repository is open source at https://github.com/roboflow/model-leaderboard. + ## License MIT β€” https://github.com/roboflow/supervision/blob/develop/LICENSE.md diff --git a/docs/metrics/mean_average_precision.md b/docs/metrics/mean_average_precision.md index 10f7a977..e8a84fbe 100644 --- a/docs/metrics/mean_average_precision.md +++ b/docs/metrics/mean_average_precision.md @@ -1,5 +1,6 @@ --- comments: true +description: API reference for MeanAveragePrecision β€” compute mAP for object detection benchmarking with bounding boxes. --- # Mean Average Precision diff --git a/docs/theme/main.html b/docs/theme/main.html index c574a2e9..32577326 100644 --- a/docs/theme/main.html +++ b/docs/theme/main.html @@ -13,11 +13,14 @@ {% block extrahead %} {{ super() }} - +{% if page.meta is defined and page.meta is not none and page.meta is not undefined %} +{% set _meta = page.meta %} +{% else %} +{% set _meta = {} %} +{% endif %} {# ── GEO: JSON-LD + OG tags (page context required β€” skip for theme templates like 404) #} -{% if page %} -{# ── GEO: JSON-LD structured data ───────────────────────────────────────── #} +{# ── GEO: JSON-LD structured data ──────────────────────────── #} -{% if page.is_homepage %} +{% for is_home in [page.is_homepage] %}{% if is_home %} -{% endif %} +{% endif %}{% endfor %} {% if 'how_to' in page.url %} {% endif %} -{% if not page.is_homepage %} +{# ── How-to FAQ schema ─────────────────────────────────────── #} +{% if 'how_to' in page.url %} + +{% endif %} + +{% for is_not_home in [not page.is_homepage] %}{% if is_not_home %} -{% endif %} +{% endif %}{% endfor %} -{# ── GEO: Open Graph + Twitter Card meta tags ────────────────────────────── #} +{# ── GEO: Open Graph + Twitter Card meta tags ──────────────── #} - + - + +{# ── API reference schema (detection/ metrics/ datasets/ reference pages) ── #} +{% for is_ref in [('reference' in page.url or 'detection/' in page.url or 'metrics/' in page.url or 'keypoint/' in page.url or 'classification/' in page.url) and 'how_to' not in page.url] %}{% if is_ref %} + +{% endif %}{% endfor %} + +{# Cookbooks FAQ schema ── #} +{% for is_cookbook in ['cookbook' in page.url] %}{% if is_cookbook %} + +{% endif %}{% endfor %} + {# 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) @@ -168,8 +313,6 @@ and comparing its contents to this meta tag before accepting IndexNow submissions. #} -{% endif %} - - + {% endblock %}