Merge pull request #493 from roboflow/develop

`supervision-0.16.0` release

.github/requirements-dev.txt

@@ -0,0 +1,17 @@
+contourpy==1.1.0 ; python_version >= "3.8" and python_full_version < "3.12.0"
+cycler==0.11.0 ; python_version >= "3.8" and python_full_version < "3.12.0"
+fonttools==4.41.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
+importlib-resources==6.0.0 ; python_version >= "3.8" and python_version < "3.10"
+kiwisolver==1.4.4 ; python_version >= "3.8" and python_full_version < "3.12.0"
+matplotlib==3.7.2 ; python_version >= "3.8" and python_full_version < "3.12.0"
+numpy==1.24.4 ; python_version >= "3.8" and python_version < "3.12"
+opencv-python-headless==4.8.0.74 ; python_version >= "3.8" and python_full_version < "3.12.0"
+packaging==23.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
+pillow==10.0.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
+pyparsing==3.0.9 ; python_version >= "3.8" and python_full_version < "3.12.0"
+python-dateutil==2.8.2 ; python_version >= "3.8" and python_full_version < "3.12.0"
+pyyaml==6.0.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
+scipy==1.10.1 ; python_version >= "3.8" and python_version < "3.12"
+six==1.16.0 ; python_version >= "3.8" and python_full_version < "3.12.0"
+zipp==3.16.2 ; python_version >= "3.8" and python_version < "3.10"
+pytest==7.4.0 ; python_version >= "3.8" and python_full_version < "3.12.0"

.github/workflows/clear-cache.yml

@@ -0,0 +1,33 @@
+
+name: Clear cache
+
+on:
+    schedule:
+      - cron: '0 0 1 * *'
+    workflow_dispatch:
+
+permissions:
+  actions: write
+
+jobs:
+  clear-cache:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clear cache
+        uses: actions/github-script@v6
+        with:
+          script: |
+            console.log("About to clear")
+            const caches = await github.rest.actions.getActionsCacheList({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+            })
+            for (const cache of caches.data.actions_caches) {
+              console.log(cache)
+              github.rest.actions.deleteActionsCacheById({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                cache_id: cache.id,
+              })
+            }
+            console.log("Clear completed")

.github/workflows/test.yml

@@ -15,12 +15,18 @@ jobs:
         uses: actions/checkout@v3
       - name: 🐍 Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4
+        # id based on python version
+        id: python-setup
         with:
           python-version: ${{ matrix.python-version }}
-      - name: 🦾 Install dependencies
+          check-latest: true
+          cache: 'pip'
+          cache-dependency-path: '**/requirements-dev.txt'
+
+      - name: 📦 Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .
-          pip install pytest
+          pip install -r .github/requirements-dev.txt
+
       - name: 🧪 Test
         run: "python -m pytest ./test"

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ ci:
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace
@@ -22,6 +22,7 @@ repos:
       - id: detect-private-key
       - id: forbid-new-submodules
       - id: pretty-format-json
+        exclude: demo.ipynb
         args: ['--autofix', '--no-sort-keys', '--indent=4']
       - id: end-of-file-fixer
       - id: mixed-line-ending
@@ -33,11 +34,6 @@ repos:
   #       name: Upgrade code
   #       args: [--py38-plus]
 
-  - repo: https://github.com/PyCQA/isort
-    rev: 5.12.0
-    hooks:
-      - id: isort
-        name: Sort imports
 
   - repo: https://github.com/PyCQA/flake8
     rev: 6.1.0

Makefile

@@ -1,22 +0,0 @@
-.PHONY: style check_code_quality
-
-export PYTHONPATH = .
-check_dirs := supervision
-
-style:
-	black  $(check_dirs)
-	isort --profile black $(check_dirs)
-
-check_code_quality:
-	black --check $(check_dirs)
-	isort --check-only --profile black $(check_dirs)
-	# stop the build if there are Python syntax errors or undefined names
-	flake8 $(check_dirs) --count --select=E9,F63,F7,F82 --show-source --statistics
-	# exit-zero treats all errors as warnings. E203 for black, E501 for docstring, W503 for line breaks before logical operators
-	flake8 $(check_dirs) --count --max-line-length=88 --exit-zero  --ignore=D --extend-ignore=E203,E501,W503  --statistics
-
-publish:
-	poetry build
-	twine upload -r testpypi dist/* -u ${PYPI_USERNAME} -p ${PYPI_TEST_PASSWORD} --verbose
-	twine check dist/*
-	twine upload dist/* -u ${PYPI_USERNAME} -p ${PYPI_PASSWORD} --verbose

README.md

@@ -19,9 +19,15 @@
   [![license](https://img.shields.io/pypi/l/supervision)](https://github.com/roboflow/supervision/blob/main/LICENSE.md)
   [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
   [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow/supervision/blob/main/demo.ipynb)
+  [![Gradio](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Roboflow/Annotators)
+  [![Discord](https://img.shields.io/discord/1159501506232451173)](https://discord.gg/GbfgXGJ8Bk)
 
 </div>
 
+<a href="https://github.com/roboflow/supervision/issues?q=is%3Aissue+label%3Ahacktoberfest+">
+  <img width="100%" src="https://media.roboflow.com/open-source/supervision/hacktoberfest-banner-3.png">
+</a>
+
 ## 👋 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! 🤝
@@ -305,6 +311,12 @@ Visit our [documentation](https://roboflow.github.io/supervision) page to learn
 
 We love your input! Please see our [contributing guide](https://github.com/roboflow/supervision/blob/main/CONTRIBUTING.md) to get started. Thank you 🙏 to all our contributors!
 
+<p align="center">
+    <a href="https://github.com/roboflow/supervision/graphs/contributors">
+      <img src="https://contrib.rocks/image?repo=roboflow/supervision" />
+    </a>
+</p>
+
 <br>
 
 <div align="center">
@@ -352,5 +364,4 @@ We love your input! Please see our [contributing guide](https://github.com/robof
       </a>
       </a>
   </div>
-
 </div>

docs/annotators.md

@@ -15,49 +15,7 @@
 
     <div class="result" markdown>
 
-    ![bounding-box-annotator-example](https://media.roboflow.com/supervision-annotator-examples/bounding-box-annotator-example.png){ align=center width="800" }
-
-    </div>
-
-=== "Mask"
-
-    ```python
-    >>> import supervision as sv
-
-    >>> image = ...
-    >>> detections = sv.Detections(...)
-
-    >>> mask_annotator = sv.MaskAnnotator()
-    >>> annotated_frame = mask_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=detections
-    ... )
-    ```
-
-    <div class="result" markdown>
-
-    ![mask-annotator-example](https://media.roboflow.com/supervision-annotator-examples/mask-annotator-example.png){ align=center width="800" }
-
-    </div>
-
-=== "Ellipse"
-
-    ```python
-    >>> import supervision as sv
-
-    >>> image = ...
-    >>> detections = sv.Detections(...)
-
-    >>> ellipse_annotator = sv.EllipseAnnotator()
-    >>> annotated_frame = ellipse_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=detections
-    ... )
-    ```
-
-    <div class="result" markdown>
-
-    ![ellipse-annotator-example](https://media.roboflow.com/supervision-annotator-examples/ellipse-annotator-example.png){ align=center width="800" }
+    ![bounding-box-annotator-example](https://media.roboflow.com/supervision-annotator-examples/bounding-box-annotator-example-purple.png){ align=center width="800" }
 
     </div>
 
@@ -78,7 +36,28 @@
 
     <div class="result" markdown>
 
-    ![box-corner-annotator-example](https://media.roboflow.com/supervision-annotator-examples/box-corner-annotator-example.png){ align=center width="800" }
+    ![box-corner-annotator-example](https://media.roboflow.com/supervision-annotator-examples/box-corner-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "BoxMask"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> box_mask_annotator = sv.BoxMaskAnnotator()
+    >>> annotated_frame = box_mask_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![box-mask-annotator-example](https://media.roboflow.com/supervision-annotator-examples/box-mask-annotator-example-purple.png){ align=center width="800" }
 
     </div>
 
@@ -99,7 +78,91 @@
 
     <div class="result" markdown>
 
-    ![circle-annotator-example](https://media.roboflow.com/supervision-annotator-examples/circle-annotator-example.png){ align=center width="800" }
+    ![circle-annotator-example](https://media.roboflow.com/supervision-annotator-examples/circle-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Dot"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> dot_annotator = sv.DotAnnotator()
+    >>> annotated_frame = dot_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![circle-annotator-example](https://media.roboflow.com/supervision-annotator-examples/dot-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Ellipse"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> ellipse_annotator = sv.EllipseAnnotator()
+    >>> annotated_frame = ellipse_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![ellipse-annotator-example](https://media.roboflow.com/supervision-annotator-examples/ellipse-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Halo"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> halo_annotator = sv.HaloAnnotator()
+    >>> annotated_frame = halo_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![ellipse-annotator-example](https://media.roboflow.com/supervision-annotator-examples/halo-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Mask"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> mask_annotator = sv.MaskAnnotator()
+    >>> annotated_frame = mask_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![mask-annotator-example](https://media.roboflow.com/supervision-annotator-examples/mask-annotator-example-purple.png){ align=center width="800" }
 
     </div>
 
@@ -120,7 +183,7 @@
 
     <div class="result" markdown>
 
-    ![label-annotator-example](https://media.roboflow.com/supervision-annotator-examples/label-annotator-example-2.png){ align=center width="800" }
+    ![label-annotator-example](https://media.roboflow.com/supervision-annotator-examples/label-annotator-example-purple.png){ align=center width="800" }
 
     </div>
 
@@ -141,7 +204,7 @@
 
     <div class="result" markdown>
 
-    ![blur-annotator-example](https://media.roboflow.com/supervision-annotator-examples/blur-annotator-example-2.png){ align=center width="800" }
+    ![blur-annotator-example](https://media.roboflow.com/supervision-annotator-examples/blur-annotator-example-purple.png){ align=center width="800" }
 
     </div>
 
@@ -149,20 +212,59 @@
 
     ```python
     >>> import supervision as sv
+    >>> from ultralytics import YOLO
 
-    >>> image = ...
-    >>> detections = sv.Detections(...)
+    >>> model = YOLO('yolov8x.pt')
 
     >>> trace_annotator = sv.TraceAnnotator()
-    >>> annotated_frame = trace_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=detections
-    ... )
+
+    >>> video_info = sv.VideoInfo.from_video_path(video_path='...')
+    >>> frames_generator = get_video_frames_generator(source_path='...')
+    >>> tracker = sv.ByteTrack()
+
+    >>> with sv.VideoSink(target_path='...', video_info=video_info) as sink:
+    ...    for frame in frames_generator:
+    ...        result = model(frame)[0]
+    ...        detections = sv.Detections.from_ultralytics(result)
+    ...        detections = tracker.update_with_detections(detections)
+    ...        annotated_frame = trace_annotator.annotate(
+    ...            scene=frame.copy(),
+    ...            detections=detections)
+    ...        sink.write_frame(frame=annotated_frame)
     ```
 
     <div class="result" markdown>
 
-    ![trace-annotator-example](https://media.roboflow.com/supervision-annotator-examples/trace-annotator-example.png){ align=center width="800" }
+    ![trace-annotator-example](https://media.roboflow.com/supervision-annotator-examples/trace-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "HeatMap"
+
+    ```python
+    >>> import supervision as sv
+    >>> from ultralytics import YOLO
+
+    >>> model = YOLO('yolov8x.pt')
+
+    >>> heat_map_annotator = sv.HeatMapAnnotator()
+
+    >>> video_info = sv.VideoInfo.from_video_path(video_path='...')
+    >>> frames_generator = get_video_frames_generator(source_path='...')
+
+    >>> with sv.VideoSink(target_path='...', video_info=video_info) as sink:
+    ...    for frame in frames_generator:
+    ...        result = model(frame)[0]
+    ...        detections = sv.Detections.from_ultralytics(result)
+    ...        annotated_frame = heat_map_annotator.annotate(
+    ...            scene=frame.copy(),
+    ...            detections=detections)
+    ...        sink.write_frame(frame=annotated_frame)
+    ```
+
+    <div class="result" markdown>
+
+    ![trace-annotator-example](https://media.roboflow.com/supervision-annotator-examples/heat-map-annotator-example-purple.png){ align=center width="800" }
 
     </div>
 
@@ -170,30 +272,50 @@
 
 :::supervision.annotators.core.BoundingBoxAnnotator
 
-## MaskAnnotator
-
-:::supervision.annotators.core.MaskAnnotator
-
-## EllipseAnnotator
-
-:::supervision.annotators.core.EllipseAnnotator
-
 ## BoxCornerAnnotator
 
 :::supervision.annotators.core.BoxCornerAnnotator
 
+## BoxMaskAnnotator
+
+:::supervision.annotators.core.BoxMaskAnnotator
+
 ## CircleAnnotator
 
 :::supervision.annotators.core.CircleAnnotator
 
+## DotAnnotator
+
+:::supervision.annotators.core.DotAnnotator
+
+## EllipseAnnotator
+
+:::supervision.annotators.core.EllipseAnnotator
+
+## HaloAnnotator
+
+:::supervision.annotators.core.HaloAnnotator
+
+## HeatMapAnnotator
+
+:::supervision.annotators.core.HeatMapAnnotator
+
+## MaskAnnotator
+
+:::supervision.annotators.core.MaskAnnotator
+
 ## LabelAnnotator
 
 :::supervision.annotators.core.LabelAnnotator
 
+## BlurAnnotator
+
+:::supervision.annotators.core.BlurAnnotator
+
 ## TraceAnnotator
 
 :::supervision.annotators.core.TraceAnnotator
 
-## BlurAnnotator
+## ColorLookup
 
-:::supervision.annotators.core.BlurAnnotator
+:::supervision.annotators.utils.ColorLookup

docs/changelog.md

@@ -1,3 +1,47 @@
+### 0.16.0 <small>October 19, 2023</small>
+
+- Added [#422](https://github.com/roboflow/supervision/pull/422): [`sv.BoxMaskAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.BoxMaskAnnotator) allowing to annotate images and videos with mox masks.
+
+- Added [#433](https://github.com/roboflow/supervision/pull/433): [`sv.HaloAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.HaloAnnotator) allowing to annotate images and videos with halo effect.
+
+```python
+>>> import supervision as sv
+
+>>> image = ...
+>>> detections = sv.Detections(...)
+
+>>> halo_annotator = sv.HaloAnnotator()
+>>> annotated_frame = halo_annotator.annotate(
+...     scene=image.copy(),
+...     detections=detections
+... )
+```
+
+- Added [#466](https://github.com/roboflow/supervision/pull/466): [`sv.HeatMapAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.HeatMapAnnotator) allowing to annotate videos with heat maps.
+
+- Added [#492](https://github.com/roboflow/supervision/pull/492): [`sv.DotAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.DotAnnotator) allowing to annotate images and videos with dots.
+
+- Added [#449](https://github.com/roboflow/supervision/pull/449): [`sv.draw_image`](https://supervision.roboflow.com/draw/utils/#supervision.draw.utils.draw_image) allowing to draw an image onto a given scene with specified opacity and dimensions.
+
+- Added [#280](https://github.com/roboflow/supervision/pull/280): [`sv.FPSMonitor`](https://supervision.roboflow.com/utils/video/#supervision.utils.video.FPSMonitor) for monitoring frames per second (FPS) to benchmark latency.
+
+- Added [#454](https://github.com/roboflow/supervision/pull/454): 🤗 Hugging Face Annotators [space](https://huggingface.co/spaces/Roboflow/Annotators).
+
+- Changed [#482](https://github.com/roboflow/supervision/pull/482): [`sv.LineZone.tigger`](https://supervision.roboflow.com/detection/tools/line_zone/#supervision.detection.line_counter.LineZone.trigger) now return `Tuple[np.ndarray, np.ndarray]`. The first array indicates which detections have crossed the line from outside to inside. The second array indicates which detections have crossed the line from inside to outside.
+
+- Changed [#465](https://github.com/roboflow/supervision/pull/465): Annotator argument name from `color_map: str` to `color_lookup: ColorLookup` enum to increase type safety.
+
+- Changed [#426](https://github.com/roboflow/supervision/pull/426): [`sv.MaskAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.MaskAnnotator) allowing 2x faster annotation.
+
+- Fixed [#477](https://github.com/roboflow/supervision/pull/477): Poetry env definition allowing proper local installation.
+
+- Fixed [#430](https://github.com/roboflow/supervision/pull/430):  [`sv.ByteTrack`](https://supervision.roboflow.com/trackers/#supervision.tracker.byte_tracker.core.ByteTrack) to return `np.array([], dtype=int)` when `svDetections` is empty.
+
+!!! warning
+
+    `sv.Detections.from_yolov8` and `sv.Classifications.from_yolov8` as those are now replaced by [`sv.Detections.from_ultralytics`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_ultralytics) and [`sv.Classifications.from_ultralytics`](https://supervision.roboflow.com/classification/core/#supervision.classification.core.Classifications.from_ultralytics).
+
+
 ### 0.15.0 <small>October 5, 2023</small>
 
 - Added [#170](https://github.com/roboflow/supervision/pull/170): [`sv.BoundingBoxAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.BoundingBoxAnnotator) allowing to annotate images and videos with bounding boxes.

docs/detection/tools/line_zone.md

@@ -0,0 +1,3 @@
+## LineZone
+
+:::supervision.detection.line_counter.LineZone

docs/draw/color.md

@@ -0,0 +1,7 @@
+## Color
+
+:::supervision.draw.color.Color
+
+## ColorPalette
+
+:::supervision.draw.color.ColorPalette

docs/draw/utils.md

@@ -17,3 +17,7 @@
 ## draw_text
 
 :::supervision.draw.utils.draw_text
+
+## draw_image
+
+:::supervision.draw.utils.draw_image

docs/how_to/detect_and_annotate.md

@@ -0,0 +1,78 @@
+With Supervision, you can easily [annotate](https://supervision.roboflow.com/annotators/) predictions obtained from a variety of object detection and segmentation models. This document outlines how to run inference using the [Ultralytics](https://github.com/ultralytics/ultralytics) YOLOv8 model, load these predictions into Supervision, and annotate the image.
+
+## Run Inference
+
+First, you'll need to obtain predictions from your object detection or segmentation model.
+```python
+import cv2
+from ultralytics import YOLO
+
+model = YOLO("yolov8n.pt")
+image = cv2.imread("image.jpg")
+results = model(image)[0]
+```
+
+## Load Predictions into Supervision
+
+Now that we have predictions from a model, we can load them into Supervision. We can do so using the [`sv.Detections.from_ultralytics`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_ultralytics) method, which accepts model results from both detection and segmentation models.
+
+```python
+import cv2
+from ultralytics import YOLO
+import supervision as sv
+
+model = YOLO("yolov8n.pt")
+image = cv2.imread("image.jpg")
+results = model(image)[0]
+detections = sv.Detections.from_ultralytics(results)
+```
+
+You can conveniently load predictions from other computer vision frameworks and libraries using:
+
+- [`from_deepsparse`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_deepsparse) ([Deepsparse](https://github.com/neuralmagic/deepsparse))
+- [`from_detectron2`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_detectron2) ([Detectron2](https://github.com/facebookresearch/detectron2))
+- [`from_mmdetection`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_mmdetection) ([MMDetection](https://github.com/open-mmlab/mmdetection))
+- [`from_roboflow`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_roboflow) ([Roboflow Inference](https://github.com/roboflow/inference))
+- [`from_sam`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_sam) ([Segment Anything Model](https://github.com/facebookresearch/segment-anything))
+- [`from_transformers`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_transformers) ([HuggingFace Transformers](https://github.com/huggingface/transformers))
+- [`from_yolo_nas`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_yolo_nas) ([YOLO-NAS](https://github.com/Deci-AI/super-gradients/blob/master/YOLONAS.md))
+
+
+## Annotate Image
+
+Finally, we can annotate the image with the predictions. Since we are working with an object detection model, we will use the [`sv.BoundingBoxAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.BoundingBoxAnnotator) and [`sv.LabelAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.LabelAnnotator) classes. If you are running the segmentation model [`sv.MaskAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.MaskAnnotator) is a drop-in replacement for [`sv.BoundingBoxAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.BoundingBoxAnnotator) that will allow you to draw masks instead of boxes.
+
+```python
+import cv2
+from ultralytics import YOLO
+import supervision as sv
+
+model = YOLO("yolov8n.pt")
+image = cv2.imread("image.jpg")
+results = model(image)[0]
+detections = sv.Detections.from_ultralytics(results)
+
+bounding_box_annotator = sv.BoundingBoxAnnotator()
+label_annotator = sv.LabelAnnotator()
+
+labels = [
+    results.names[class_id]
+    for class_id
+    in detections.class_id
+]
+
+annotated_image = bounding_box_annotator.annotate(
+    scene=image, detections=detections)
+annotated_image = label_annotator.annotate(
+    scene=annotated_image, detections=detections, labels=labels)
+```
+
+![Predictions plotted on an image](https://media.roboflow.com/supervision_annotate_example.png)
+
+## Display Annotated Image
+
+To display the annotated image in Jupyter Notebook or Google Colab, use the [`sv.plot_image`](https://supervision.roboflow.com/utils/notebook/#supervision.utils.notebook.plot_image) function.
+
+```python
+sv.plot_image(annotated_image)
+```

docs/how_to/evaluate_model.md

@@ -0,0 +1 @@
+🚧 Page under construction.

docs/how_to/filter_detections.md

@@ -1,6 +1,3 @@
-## advanced filtering
-
-
 The advanced filtering capabilities of the `Detections` class offer users a versatile and efficient way to narrow down
 and refine object detections. This section outlines various filtering methods, including filtering by specific class
 or a set of classes, confidence, object area, bounding box area, relative area, box dimensions, and designated zones.

docs/how_to/process_video.md

@@ -0,0 +1 @@
+🚧 Page under construction.

docs/how_to/track_objects.md

@@ -0,0 +1 @@
+🚧 Page under construction.

docs/index.md

@@ -46,6 +46,7 @@ You can install `supervision` with pip in a
         # setup python environment and activate it
         python3 -m venv venv
         source venv/bin/activate
+        pip install --upgrade pip
 
         # headless install
         pip install -e "."
@@ -62,7 +63,7 @@ You can install `supervision` with pip in a
         cd supervision
 
         # setup python environment and activate it
-        poetry env use python 3.10
+        poetry env use python3.10
         poetry shell
 
         # headless install

docs/utils/video.md

@@ -6,6 +6,10 @@
 
 :::supervision.utils.video.VideoSink
 
+## FPSMonitor
+
+:::supervision.utils.video.FPSMonitor
+
 ## get_video_frames_generator
 
 :::supervision.utils.video.get_video_frames_generator

examples/README.md

@@ -0,0 +1,31 @@
+## Supervision Examples
+
+This repository is packed with real-world use-cases, provided through Python scripts or
+interactive notebooks. Browse through to understand how the Supervision library
+interfaces with diverse applications.
+
+|               **Title**                |             **Contributor**              |
+|:--------------------------------------:|:----------------------------------------:|
+|         [Tracking](./tracking)         | [@SkalskiP](https://github.com/SkalskiP) |
+| [Traffic Analysis](./traffic_analysis) | [@SkalskiP](https://github.com/SkalskiP) |
+
+
+## Guidelines for Contributing
+
+We welcome contributions from the community in the form of examples, applications, and
+guides. To contribute, please follow these steps:
+
+1. Create a pull request (PR) with the `[Example]` prefix in the title, adding your
+project folder to the `examples/` directory in the repository.
+2. Confirm your project aligns with the following standards:
+   - Incorporates the `supervision` package.
+   - Provides a `README.md` file, detailing the instructions to execute the project.
+   - Showcases visual results, demonstrating the app's functionality.
+   - Avoids adding large assets or dependencies unless absolutely necessary.
+   - The contributor is expected to provide support for issues related to their
+examples.
+   - In case the presented model has licensing complications, kindly specify them to
+circumvent potential misunderstandings.
+
+For inquiries or concerns about these prerequisites, feel free to raise a PR. We are
+committed to assist and guide you.

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: Supervision
-site_url: https://roboflow.github.io/supervision
+site_url: https://supervision.roboflow.com/
 site_author: Roboflow
 site_description: A set of easy-to-use utils that will come in handy in any Computer Vision project
 repo_name: roboflow/supervision
@@ -26,29 +26,35 @@ extra_css:
 
 nav:
   - Home: index.md
-  - Quickstart:
-    - Detections: quickstart/detections.md
-  - Classifications:
-      - Core: classification/core.md
-  - Detections:
-      - Core: detection/core.md
-      - Annotate: detection/annotate.md
-      - Utils: detection/utils.md
-      - Tools:
-          - Polygon Zone: detection/tools/polygon_zone.md
-          - Inference Slicer: detection/tools/inference_slicer.md
-  - Annotators: annotators.md
-  - Trackers: trackers.md
-  - Datasets: datasets.md
-  - Metrics:
-    - Object Detection: metrics/detection.md
-  - Draw:
-      - Utils: draw/utils.md
-  - Utils:
-      - Video: utils/video.md
-      - Image: utils/image.md
-      - Notebook: utils/notebook.md
-      - File: utils/file.md
+  - How to:
+      - Detect and Annotate: how_to/detect_and_annotate.md
+      - Process Video: how_to/process_video.md
+      - Track Objects: how_to/track_objects.md
+      - Filter Detections: how_to/filter_detections.md
+      - Evaluate Model: how_to/evaluate_model.md
+  - API:
+    - Classifications:
+        - Core: classification/core.md
+    - Detections:
+        - Core: detection/core.md
+        - Utils: detection/utils.md
+    - Tools:
+        - Line Zone: detection/tools/line_zone.md
+        - Polygon Zone: detection/tools/polygon_zone.md
+        - Inference Slicer: detection/tools/inference_slicer.md
+    - Annotators: annotators.md
+    - Trackers: trackers.md
+    - Datasets: datasets.md
+    - Metrics:
+      - Object Detection: metrics/detection.md
+    - Draw:
+        - Color: draw/color.md
+        - Utils: draw/utils.md
+    - Utils:
+        - Video: utils/video.md
+        - Image: utils/image.md
+        - Notebook: utils/notebook.md
+        - File: utils/file.md
   - Changelog: changelog.md
 
 theme:

poetry.lock

@@ -3358,13 +3358,13 @@ dev = ["flake8", "flake8-annotations", "flake8-bandit", "flake8-bugbear", "flake
 
 [[package]]
 name = "urllib3"
-version = "2.0.6"
+version = "2.0.7"
 description = "HTTP library with thread-safe connection pooling, file post, and more."
 optional = false
 python-versions = ">=3.7"
 files = [
-    {file = "urllib3-2.0.6-py3-none-any.whl", hash = "sha256:7a7c7003b000adf9e7ca2a377c9688bbc54ed41b985789ed576570342a375cd2"},
-    {file = "urllib3-2.0.6.tar.gz", hash = "sha256:b19e1a85d206b56d7df1d5e683df4a7725252a964e3993648dd0fb5a1c157564"},
+    {file = "urllib3-2.0.7-py3-none-any.whl", hash = "sha256:fdb6d215c776278489906c2f8916e6e7d4f5a9b602ccbcfdf7f016fc8da0596e"},
+    {file = "urllib3-2.0.7.tar.gz", hash = "sha256:c97dfde1f7bd43a71c8d2a58e369e9b2bf692d1334ea9f9cae55add7d0dd0f84"},
 ]
 
 [package.extras]

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "supervision"
-version = "0.15.0"
+version = "0.16.0"
 description = "A set of easy-to-use utils that will come in handy in any Computer Vision project"
 authors = ["Piotr Skalski <piotr.skalski92@gmail.com>"]
 maintainers = ["Piotr Skalski <piotr.skalski92@gmail.com>"]
@@ -176,7 +176,7 @@ max-args = 20
 include-package-data = false
 
 [tool.setuptools.packages.find]
-exclude = ["docs*", "test*"]
+exclude = ["docs*", "test*","examples*"]
 
 [build-system]
 requires = ["poetry-core"]

supervision/__init__.py

@@ -10,12 +10,17 @@ from supervision.annotators.core import (
     BlurAnnotator,
     BoundingBoxAnnotator,
     BoxCornerAnnotator,
+    BoxMaskAnnotator,
     CircleAnnotator,
+    DotAnnotator,
     EllipseAnnotator,
+    HaloAnnotator,
+    HeatMapAnnotator,
     LabelAnnotator,
     MaskAnnotator,
     TraceAnnotator,
 )
+from supervision.annotators.utils import ColorLookup
 from supervision.classification.core import Classifications
 from supervision.dataset.core import (
     BaseDataset,
@@ -37,7 +42,14 @@ from supervision.detection.utils import (
     polygon_to_xyxy,
 )
 from supervision.draw.color import Color, ColorPalette
-from supervision.draw.utils import draw_filled_rectangle, draw_polygon, draw_text
+from supervision.draw.utils import (
+    draw_filled_rectangle,
+    draw_image,
+    draw_line,
+    draw_polygon,
+    draw_rectangle,
+    draw_text,
+)
 from supervision.geometry.core import Point, Position, Rect
 from supervision.geometry.utils import get_polygon_center
 from supervision.metrics.detection import ConfusionMatrix, MeanAveragePrecision
@@ -46,6 +58,7 @@ from supervision.utils.file import list_files_with_extensions
 from supervision.utils.image import ImageSink, crop_image
 from supervision.utils.notebook import plot_image, plot_images_grid
 from supervision.utils.video import (
+    FPSMonitor,
     VideoInfo,
     VideoSink,
     get_video_frames_generator,

supervision/annotators/core.py

@@ -5,12 +5,7 @@ import cv2
 import numpy as np
 
 from supervision.annotators.base import BaseAnnotator
-from supervision.annotators.utils import (
-    ColorMap,
-    Trace,
-    resolve_color,
-    resolve_color_idx,
-)
+from supervision.annotators.utils import ColorLookup, Trace, resolve_color
 from supervision.detection.core import Detections
 from supervision.draw.color import Color, ColorPalette
 from supervision.geometry.core import Position
@@ -25,27 +20,34 @@ class BoundingBoxAnnotator(BaseAnnotator):
         self,
         color: Union[Color, ColorPalette] = ColorPalette.default(),
         thickness: int = 2,
-        color_map: str = "class",
+        color_lookup: ColorLookup = ColorLookup.CLASS,
     ):
         """
         Args:
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating detections.
             thickness (int): Thickness of the bounding box lines.
-            color_map (str): Strategy for mapping colors to annotations.
-                Options are `index`, `class`, or `track`.
+            color_lookup (str): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACE`.
         """
         self.color: Union[Color, ColorPalette] = color
         self.thickness: int = thickness
-        self.color_map: ColorMap = ColorMap(color_map)
+        self.color_lookup: ColorLookup = color_lookup
 
-    def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
+    def annotate(
+        self,
+        scene: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray] = None,
+    ) -> np.ndarray:
         """
         Annotates the given scene with bounding boxes based on the provided detections.
 
         Args:
             scene (np.ndarray): The image where bounding boxes will be drawn.
             detections (Detections): Object detections to annotate.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
 
         Returns:
             np.ndarray: The annotated image.
@@ -65,16 +67,18 @@ class BoundingBoxAnnotator(BaseAnnotator):
             ```
 
         ![bounding-box-annotator-example](https://media.roboflow.com/
-        supervision-annotator-examples/bounding-box-annotator-example.png)
+        supervision-annotator-examples/bounding-box-annotator-example-purple.png)
         """
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
-            idx = resolve_color_idx(
+            color = resolve_color(
+                color=self.color,
                 detections=detections,
                 detection_idx=detection_idx,
-                color_map=self.color_map,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
             )
-            color = resolve_color(color=self.color, idx=idx)
             cv2.rectangle(
                 img=scene,
                 pt1=(x1, y1),
@@ -94,27 +98,34 @@ class MaskAnnotator(BaseAnnotator):
         self,
         color: Union[Color, ColorPalette] = ColorPalette.default(),
         opacity: float = 0.5,
-        color_map: str = "class",
+        color_lookup: ColorLookup = ColorLookup.CLASS,
     ):
         """
         Args:
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating detections.
             opacity (float): Opacity of the overlay mask. Must be between `0` and `1`.
-            color_map (str): Strategy for mapping colors to annotations.
-                Options are `index`, `class`, or `track`.
+            color_lookup (str): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACE`.
         """
         self.color: Union[Color, ColorPalette] = color
         self.opacity = opacity
-        self.color_map: ColorMap = ColorMap(color_map)
+        self.color_lookup: ColorLookup = color_lookup
 
-    def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
+    def annotate(
+        self,
+        scene: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray] = None,
+    ) -> np.ndarray:
         """
         Annotates the given scene with masks based on the provided detections.
 
         Args:
             scene (np.ndarray): The image where masks will be drawn.
             detections (Detections): Object detections to annotate.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
 
         Returns:
             np.ndarray: The annotated image.
@@ -134,27 +145,201 @@ class MaskAnnotator(BaseAnnotator):
             ```
 
         ![mask-annotator-example](https://media.roboflow.com/
-        supervision-annotator-examples/mask-annotator-example.png)
+        supervision-annotator-examples/mask-annotator-example-purple.png)
         """
         if detections.mask is None:
             return scene
 
         for detection_idx in np.flip(np.argsort(detections.area)):
-            idx = resolve_color_idx(
+            color = resolve_color(
+                color=self.color,
                 detections=detections,
                 detection_idx=detection_idx,
-                color_map=self.color_map,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
             )
-            color = resolve_color(color=self.color, idx=idx)
             mask = detections.mask[detection_idx]
             colored_mask = np.zeros_like(scene, dtype=np.uint8)
             colored_mask[:] = color.as_bgr()
+            scene[mask] = cv2.addWeighted(
+                colored_mask, self.opacity, scene, 1 - self.opacity, 0
+            )[mask]
 
-            scene = np.where(
-                np.expand_dims(mask, axis=-1),
-                np.uint8(self.opacity * colored_mask + (1 - self.opacity) * scene),
-                scene,
+        return scene
+
+
+class BoxMaskAnnotator(BaseAnnotator):
+    """
+    A class for drawing box masks on an image using provided detections.
+    """
+
+    def __init__(
+        self,
+        color: Union[Color, ColorPalette] = ColorPalette.default(),
+        opacity: float = 0.5,
+        color_lookup: ColorLookup = ColorLookup.CLASS,
+    ):
+        """
+        Args:
+            color (Union[Color, ColorPalette]): The color or color palette to use for
+                annotating detections.
+            opacity (float): Opacity of the overlay mask. Must be between `0` and `1`.
+            color_lookup (str): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACE`.
+        """
+        self.color: Union[Color, ColorPalette] = color
+        self.color_lookup: ColorLookup = color_lookup
+        self.opacity = opacity
+
+    def annotate(
+        self,
+        scene: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray] = None,
+    ) -> np.ndarray:
+        """
+        Annotates the given scene with box masks based on the provided detections.
+
+        Args:
+            scene (np.ndarray): The image where bounding boxes will be drawn.
+            detections (Detections): Object detections to annotate.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
+
+        Returns:
+            np.ndarray: The annotated image.
+
+        Example:
+            ```python
+            >>> import supervision as sv
+
+            >>> image = ...
+            >>> detections = sv.Detections(...)
+
+            >>> box_mask_annotator = sv.BoxMaskAnnotator()
+            >>> annotated_frame = box_mask_annotator.annotate(
+            ...     scene=image.copy(),
+            ...     detections=detections
+            ... )
+            ```
+
+        ![box-mask-annotator-example](https://media.roboflow.com/
+        supervision-annotator-examples/box-mask-annotator-example-purple.png)
+        """
+        mask_image = scene.copy()
+        for detection_idx in range(len(detections)):
+            x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
+            color = resolve_color(
+                color=self.color,
+                detections=detections,
+                detection_idx=detection_idx,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
             )
+            cv2.rectangle(
+                img=scene,
+                pt1=(x1, y1),
+                pt2=(x2, y2),
+                color=color.as_bgr(),
+                thickness=-1,
+            )
+        scene = cv2.addWeighted(
+            scene, self.opacity, mask_image, 1 - self.opacity, gamma=0
+        )
+        return scene
+
+
+class HaloAnnotator(BaseAnnotator):
+    """
+    A class for drawing Halos on an image using provided detections.
+    """
+
+    def __init__(
+        self,
+        color: Union[Color, ColorPalette] = ColorPalette.default(),
+        opacity: float = 0.8,
+        kernel_size: int = 40,
+        color_lookup: ColorLookup = ColorLookup.CLASS,
+    ):
+        """
+        Args:
+            color (Union[Color, ColorPalette]): The color or color palette to use for
+                annotating detections.
+            opacity (float): Opacity of the overlay mask. Must be between `0` and `1`.
+            kernel_size (int): The size of the average pooling kernel used for creating
+                the halo.
+            color_lookup (str): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACE`.
+        """
+        self.color: Union[Color, ColorPalette] = color
+        self.opacity = opacity
+        self.color_lookup: ColorLookup = color_lookup
+        self.kernel_size: int = kernel_size
+
+    def annotate(
+        self,
+        scene: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray] = None,
+    ) -> np.ndarray:
+        """
+        Annotates the given scene with halos based on the provided detections.
+
+        Args:
+            scene (np.ndarray): The image where masks will be drawn.
+            detections (Detections): Object detections to annotate.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
+
+        Returns:
+            np.ndarray: The annotated image.
+
+        Example:
+            ```python
+            >>> import supervision as sv
+
+            >>> image = ...
+            >>> detections = sv.Detections(...)
+
+            >>> halo_annotator = sv.HaloAnnotator()
+            >>> annotated_frame = halo_annotator.annotate(
+            ...     scene=image.copy(),
+            ...     detections=detections
+            ... )
+            ```
+
+        ![halo-annotator-example](https://media.roboflow.com/
+        supervision-annotator-examples/halo-annotator-example-purple.png)
+        """
+        if detections.mask is None:
+            return scene
+        colored_mask = np.zeros_like(scene, dtype=np.uint8)
+        fmask = np.array([False] * scene.shape[0] * scene.shape[1]).reshape(
+            scene.shape[0], scene.shape[1]
+        )
+
+        for detection_idx in np.flip(np.argsort(detections.area)):
+            color = resolve_color(
+                color=self.color,
+                detections=detections,
+                detection_idx=detection_idx,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
+            )
+            mask = detections.mask[detection_idx]
+            fmask = np.logical_or(fmask, mask)
+            color_bgr = color.as_bgr()
+            colored_mask[mask] = color_bgr
+
+        colored_mask = cv2.blur(colored_mask, (self.kernel_size, self.kernel_size))
+        colored_mask[fmask] = [0, 0, 0]
+        gray = cv2.cvtColor(colored_mask, cv2.COLOR_BGR2GRAY)
+        alpha = self.opacity * gray / gray.max()
+        alpha_mask = alpha[:, :, np.newaxis]
+        scene = np.uint8(scene * (1 - alpha_mask) + colored_mask * self.opacity)
         return scene
 
 
@@ -169,7 +354,7 @@ class EllipseAnnotator(BaseAnnotator):
         thickness: int = 2,
         start_angle: int = -45,
         end_angle: int = 235,
-        color_map: str = "class",
+        color_lookup: ColorLookup = ColorLookup.CLASS,
     ):
         """
         Args:
@@ -178,22 +363,29 @@ class EllipseAnnotator(BaseAnnotator):
             thickness (int): Thickness of the ellipse lines.
             start_angle (int): Starting angle of the ellipse.
             end_angle (int): Ending angle of the ellipse.
-            color_map (str): Strategy for mapping colors to annotations.
-                Options are `index`, `class`, or `track`.
+            color_lookup (str): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACE`.
         """
         self.color: Union[Color, ColorPalette] = color
         self.thickness: int = thickness
         self.start_angle: int = start_angle
         self.end_angle: int = end_angle
-        self.color_map: ColorMap = ColorMap(color_map)
+        self.color_lookup: ColorLookup = color_lookup
 
-    def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
+    def annotate(
+        self,
+        scene: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray] = None,
+    ) -> np.ndarray:
         """
         Annotates the given scene with ellipses based on the provided detections.
 
         Args:
             scene (np.ndarray): The image where ellipses will be drawn.
             detections (Detections): Object detections to annotate.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
 
         Returns:
             np.ndarray: The annotated image.
@@ -213,17 +405,18 @@ class EllipseAnnotator(BaseAnnotator):
             ```
 
         ![ellipse-annotator-example](https://media.roboflow.com/
-        supervision-annotator-examples/ellipse-annotator-example.png)
+        supervision-annotator-examples/ellipse-annotator-example-purple.png)
         """
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
-            idx = resolve_color_idx(
+            color = resolve_color(
+                color=self.color,
                 detections=detections,
                 detection_idx=detection_idx,
-                color_map=self.color_map,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
             )
-            color = resolve_color(color=self.color, idx=idx)
-
             center = (int((x1 + x2) / 2), y2)
             width = x2 - x1
             cv2.ellipse(
@@ -249,8 +442,8 @@ class BoxCornerAnnotator(BaseAnnotator):
         self,
         color: Union[Color, ColorPalette] = ColorPalette.default(),
         thickness: int = 4,
-        corner_length: int = 25,
-        color_map: str = "class",
+        corner_length: int = 15,
+        color_lookup: ColorLookup = ColorLookup.CLASS,
     ):
         """
         Args:
@@ -258,21 +451,28 @@ class BoxCornerAnnotator(BaseAnnotator):
                 annotating detections.
             thickness (int): Thickness of the corner lines.
             corner_length (int): Length of each corner line.
-            color_map (str): Strategy for mapping colors to annotations.
-                Options are `index`, `class`, or `track`.
+            color_lookup (str): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACE`.
         """
         self.color: Union[Color, ColorPalette] = color
         self.thickness: int = thickness
         self.corner_length: int = corner_length
-        self.color_map: ColorMap = ColorMap(color_map)
+        self.color_lookup: ColorLookup = color_lookup
 
-    def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
+    def annotate(
+        self,
+        scene: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray] = None,
+    ) -> np.ndarray:
         """
         Annotates the given scene with box corners based on the provided detections.
 
         Args:
             scene (np.ndarray): The image where box corners will be drawn.
             detections (Detections): Object detections to annotate.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
 
         Returns:
             np.ndarray: The annotated image.
@@ -292,16 +492,18 @@ class BoxCornerAnnotator(BaseAnnotator):
             ```
 
         ![box-corner-annotator-example](https://media.roboflow.com/
-        supervision-annotator-examples/box-corner-annotator-example.png)
+        supervision-annotator-examples/box-corner-annotator-example-purple.png)
         """
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
-            idx = resolve_color_idx(
+            color = resolve_color(
+                color=self.color,
                 detections=detections,
                 detection_idx=detection_idx,
-                color_map=self.color_map,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
             )
-            color = resolve_color(color=self.color, idx=idx)
             corners = [(x1, y1), (x2, y1), (x1, y2), (x2, y2)]
 
             for x, y in corners:
@@ -325,26 +527,27 @@ class CircleAnnotator(BaseAnnotator):
     def __init__(
         self,
         color: Union[Color, ColorPalette] = ColorPalette.default(),
-        thickness: int = 4,
-        color_map: str = "class",
+        thickness: int = 2,
+        color_lookup: ColorLookup = ColorLookup.CLASS,
     ):
         """
         Args:
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating detections.
             thickness (int): Thickness of the circle line.
-            color_map (str): Strategy for mapping colors to annotations.
-                Options are `index`, `class`, or `track`.
+            color_lookup (str): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACE`.
         """
 
         self.color: Union[Color, ColorPalette] = color
         self.thickness: int = thickness
-        self.color_map: ColorMap = ColorMap(color_map)
+        self.color_lookup: ColorLookup = color_lookup
 
     def annotate(
         self,
         scene: np.ndarray,
         detections: Detections,
+        custom_color_lookup: Optional[np.ndarray] = None,
     ) -> np.ndarray:
         """
         Annotates the given scene with circles based on the provided detections.
@@ -352,6 +555,8 @@ class CircleAnnotator(BaseAnnotator):
         Args:
             scene (np.ndarray): The image where box corners will be drawn.
             detections (Detections): Object detections to annotate.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
 
         Returns:
             np.ndarray: The annotated image.
@@ -372,25 +577,20 @@ class CircleAnnotator(BaseAnnotator):
 
 
         ![circle-annotator-example](https://media.roboflow.com/
-        supervision-annotator-examples/circle-annotator-example.png)
+        supervision-annotator-examples/circle-annotator-example-purple.png)
         """
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
             center = ((x1 + x2) // 2, (y1 + y2) // 2)
             distance = sqrt((x1 - center[0]) ** 2 + (y1 - center[1]) ** 2)
-
-            idx = resolve_color_idx(
+            color = resolve_color(
+                color=self.color,
                 detections=detections,
                 detection_idx=detection_idx,
-                color_map=self.color_map,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
             )
-
-            color = (
-                self.color.by_idx(idx)
-                if isinstance(self.color, ColorPalette)
-                else self.color
-            )
-
             cv2.circle(
                 img=scene,
                 center=center,
@@ -402,6 +602,83 @@ class CircleAnnotator(BaseAnnotator):
         return scene
 
 
+class DotAnnotator(BaseAnnotator):
+    """
+    A class for drawing dots on an image at specific coordinates based on provided
+    detections.
+    """
+
+    def __init__(
+        self,
+        color: Union[Color, ColorPalette] = ColorPalette.default(),
+        radius: int = 4,
+        position: Position = Position.CENTER,
+        color_lookup: ColorLookup = ColorLookup.CLASS,
+    ):
+        """
+        Args:
+            color (Union[Color, ColorPalette]): The color or color palette to use for
+                annotating detections.
+            radius (int): Radius of the drawn dots.
+            position (Position): The anchor position for placing the dot.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACE`.
+        """
+        self.color: Union[Color, ColorPalette] = color
+        self.radius: int = radius
+        self.position: Position = position
+        self.color_lookup: ColorLookup = color_lookup
+
+    def annotate(
+        self,
+        scene: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray] = None,
+    ) -> np.ndarray:
+        """
+        Annotates the given scene with dots based on the provided detections.
+
+        Args:
+            scene (np.ndarray): The image where dots will be drawn.
+            detections (Detections): Object detections to annotate.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
+
+        Returns:
+            np.ndarray: The annotated image.
+
+        Example:
+            ```python
+            >>> import supervision as sv
+
+            >>> image = ...
+            >>> detections = sv.Detections(...)
+
+            >>> dot_annotator = sv.DotAnnotator()
+            >>> annotated_frame = dot_annotator.annotate(
+            ...     scene=image.copy(),
+            ...     detections=detections
+            ... )
+            ```
+
+        ![dot-annotator-example](https://media.roboflow.com/
+        supervision-annotator-examples/dot-annotator-example-purple.png)
+        """
+        xy = detections.get_anchor_coordinates(anchor=self.position)
+        for detection_idx in range(len(detections)):
+            color = resolve_color(
+                color=self.color,
+                detections=detections,
+                detection_idx=detection_idx,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
+            )
+            center = (int(xy[detection_idx, 0]), int(xy[detection_idx, 1]))
+            cv2.circle(scene, center, self.radius, color.as_bgr(), -1)
+        return scene
+
+
 class LabelAnnotator:
     """
     A class for annotating labels on an image using provided detections.
@@ -415,7 +692,7 @@ class LabelAnnotator:
         text_thickness: int = 1,
         text_padding: int = 10,
         text_position: Position = Position.TOP_LEFT,
-        color_map: str = "class",
+        color_lookup: ColorLookup = ColorLookup.CLASS,
     ):
         """
         Args:
@@ -427,8 +704,8 @@ class LabelAnnotator:
             text_padding (int): Padding around the text within its background box.
             text_position (Position): Position of the text relative to the detection.
                 Possible values are defined in the `Position` enum.
-            color_map (str): Strategy for mapping colors to annotations.
-                Options are `index`, `class`, or `track`.
+            color_lookup (str): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACE`.
         """
         self.color: Union[Color, ColorPalette] = color
         self.text_color: Color = text_color
@@ -436,7 +713,7 @@ class LabelAnnotator:
         self.text_thickness: int = text_thickness
         self.text_padding: int = text_padding
         self.text_position: Position = text_position
-        self.color_map: ColorMap = ColorMap(color_map)
+        self.color_lookup: ColorLookup = color_lookup
 
     @staticmethod
     def resolve_text_background_xyxy(
@@ -485,6 +762,7 @@ class LabelAnnotator:
         scene: np.ndarray,
         detections: Detections,
         labels: List[str] = None,
+        custom_color_lookup: Optional[np.ndarray] = None,
     ) -> np.ndarray:
         """
         Annotates the given scene with labels based on the provided detections.
@@ -493,6 +771,8 @@ class LabelAnnotator:
             scene (np.ndarray): The image where labels will be drawn.
             detections (Detections): Object detections to annotate.
             labels (List[str]): Optional. Custom labels for each detection.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
 
         Returns:
             np.ndarray: The annotated image.
@@ -512,17 +792,19 @@ class LabelAnnotator:
             ```
 
         ![label-annotator-example](https://media.roboflow.com/
-        supervision-annotator-examples/label-annotator-example-2.png)
+        supervision-annotator-examples/label-annotator-example-purple.png)
         """
         font = cv2.FONT_HERSHEY_SIMPLEX
         for detection_idx in range(len(detections)):
             detection_xyxy = detections.xyxy[detection_idx].astype(int)
-            idx = resolve_color_idx(
+            color = resolve_color(
+                color=self.color,
                 detections=detections,
                 detection_idx=detection_idx,
-                color_map=self.color_map,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
             )
-            color = resolve_color(color=self.color, idx=idx)
             text = (
                 f"{detections.class_id[detection_idx]}"
                 if (labels is None or len(detections) != len(labels))
@@ -607,7 +889,7 @@ class BlurAnnotator(BaseAnnotator):
             ```
 
         ![blur-annotator-example](https://media.roboflow.com/
-        supervision-annotator-examples/blur-annotator-example-2.png)
+        supervision-annotator-examples/blur-annotator-example-purple.png)
         """
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
@@ -633,30 +915,35 @@ class TraceAnnotator:
     def __init__(
         self,
         color: Union[Color, ColorPalette] = ColorPalette.default(),
-        position: Optional[Position] = Position.CENTER,
+        position: Position = Position.CENTER,
         trace_length: int = 30,
         thickness: int = 2,
-        color_map: str = "class",
+        color_lookup: ColorLookup = ColorLookup.CLASS,
     ):
         """
         Args:
             color (Union[Color, ColorPalette]): The color to draw the trace, can be
                 a single color or a color palette.
-            position (Optional[Position]): The position of the trace.
+            position (Position): The position of the trace.
                 Defaults to `CENTER`.
             trace_length (int): The maximum length of the trace in terms of historical
                 points. Defaults to `30`.
             thickness (int): The thickness of the trace lines. Defaults to `2`.
-            color_map (str): Strategy for mapping colors to annotations.
-                Options are `index`, `class`, or `track`.
+            color_lookup (str): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACE`.
         """
         self.color: Union[Color, ColorPalette] = color
         self.position = position
         self.trace = Trace(max_size=trace_length)
         self.thickness = thickness
-        self.color_map: ColorMap = ColorMap(color_map)
+        self.color_lookup: ColorLookup = color_lookup
 
-    def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
+    def annotate(
+        self,
+        scene: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray] = None,
+    ) -> np.ndarray:
         """
         Draws trace paths on the frame based on the detection coordinates provided.
 
@@ -664,6 +951,8 @@ class TraceAnnotator:
             scene (np.ndarray): The image on which the traces will be drawn.
             detections (Detections): The detections which include coordinates for
                 which the traces will be drawn.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
 
         Returns:
             np.ndarray: The image with the trace paths drawn on it.
@@ -671,30 +960,42 @@ class TraceAnnotator:
         Example:
             ```python
             >>> import supervision as sv
+            >>> from ultralytics import YOLO
 
-            >>> image = ...
-            >>> detections = sv.Detections(...)
+            >>> model = YOLO('yolov8x.pt')
 
             >>> trace_annotator = sv.TraceAnnotator()
-            >>> annotated_frame = trace_annotator.annotate(
-            ...     scene=image.copy(),
-            ...     detections=detections
-            ... )
+
+            >>> video_info = sv.VideoInfo.from_video_path(video_path='...')
+            >>> frames_generator = sv.get_video_frames_generator(source_path='...')
+            >>> tracker = sv.ByteTrack()
+
+            >>> with sv.VideoSink(target_path='...', video_info=video_info) as sink:
+            ...    for frame in frames_generator:
+            ...        result = model(frame)[0]
+            ...        detections = sv.Detections.from_ultralytics(result)
+            ...        detections = tracker.update_with_detections(detections)
+            ...        annotated_frame = trace_annotator.annotate(
+            ...            scene=frame.copy(),
+            ...            detections=detections)
+            ...        sink.write_frame(frame=annotated_frame)
             ```
 
         ![trace-annotator-example](https://media.roboflow.com/
-        supervision-annotator-examples/trace-annotator-example.png)
+        supervision-annotator-examples/trace-annotator-example-purple.png)
         """
         self.trace.put(detections)
 
         for detection_idx in range(len(detections)):
             tracker_id = int(detections.tracker_id[detection_idx])
-            idx = resolve_color_idx(
+            color = resolve_color(
+                color=self.color,
                 detections=detections,
                 detection_idx=detection_idx,
-                color_map=self.color_map,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
             )
-            color = resolve_color(color=self.color, idx=idx)
             xy = self.trace.get(tracker_id=tracker_id)
             if len(xy) > 1:
                 scene = cv2.polylines(
@@ -705,3 +1006,97 @@ class TraceAnnotator:
                     thickness=self.thickness,
                 )
         return scene
+
+
+class HeatMapAnnotator:
+    """
+    A class for drawing heatmaps on an image based on provided detections.
+    Heat accumulates over time and is drawn as a semi-transparent overlay
+    of blurred circles.
+    """
+
+    def __init__(
+        self,
+        position: Position = Position.BOTTOM_CENTER,
+        opacity: float = 0.2,
+        radius: int = 40,
+        kernel_size: int = 25,
+        top_hue: int = 0,
+        low_hue: int = 125,
+    ):
+        """
+        Args:
+            position (Position): The position of the heatmap. Defaults to
+                `BOTTOM_CENTER`.
+            opacity (float): Opacity of the overlay mask, between 0 and 1.
+            radius (int): Radius of the heat circle.
+            kernel_size (int): Kernel size for blurring the heatmap.
+            top_hue (int): Hue at the top of the heatmap. Defaults to 0 (red).
+            low_hue (int): Hue at the bottom of the heatmap. Defaults to 125 (blue).
+        """
+        self.position = position
+        self.opacity = opacity
+        self.radius = radius
+        self.kernel_size = kernel_size
+        self.heat_mask = None
+        self.top_hue = top_hue
+        self.low_hue = low_hue
+
+    def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
+        """
+        Annotates the scene with a heatmap based on the provided detections.
+
+        Args:
+            scene (np.ndarray): The image where the heatmap will be drawn.
+            detections (Detections): Object detections to annotate.
+
+        Returns:
+            np.ndarray: Annotated image.
+
+        Example:
+            ```python
+            >>> import supervision as sv
+            >>> from ultralytics import YOLO
+
+            >>> model = YOLO('yolov8x.pt')
+
+            >>> heat_map_annotator = sv.HeatMapAnnotator()
+
+            >>> video_info = sv.VideoInfo.from_video_path(video_path='...')
+            >>> frames_generator = get_video_frames_generator(source_path='...')
+
+            >>> with sv.VideoSink(target_path='...', video_info=video_info) as sink:
+            ...    for frame in frames_generator:
+            ...        result = model(frame)[0]
+            ...        detections = sv.Detections.from_ultralytics(result)
+            ...        annotated_frame = heat_map_annotator.annotate(
+            ...            scene=frame.copy(),
+            ...            detections=detections)
+            ...        sink.write_frame(frame=annotated_frame)
+            ```
+
+        ![heatmap-annotator-example](https://media.roboflow.com/
+        supervision-annotator-examples/heat-map-annotator-example-purple.png)
+        """
+
+        if self.heat_mask is None:
+            self.heat_mask = np.zeros(scene.shape[:2])
+        mask = np.zeros(scene.shape[:2])
+        for xy in detections.get_anchor_coordinates(self.position):
+            cv2.circle(mask, (int(xy[0]), int(xy[1])), self.radius, 1, -1)
+        self.heat_mask = mask + self.heat_mask
+        temp = self.heat_mask.copy()
+        temp = self.low_hue - temp / temp.max() * (self.low_hue - self.top_hue)
+        temp = temp.astype(np.uint8)
+        if self.kernel_size is not None:
+            temp = cv2.blur(temp, (self.kernel_size, self.kernel_size))
+        hsv = np.zeros(scene.shape)
+        hsv[..., 0] = temp
+        hsv[..., 1] = 255
+        hsv[..., 2] = 255
+        temp = cv2.cvtColor(hsv.astype(np.uint8), cv2.COLOR_HSV2BGR)
+        mask = cv2.cvtColor(self.heat_mask.astype(np.uint8), cv2.COLOR_GRAY2BGR) > 0
+        scene[mask] = cv2.addWeighted(temp, self.opacity, scene, 1 - self.opacity, 0)[
+            mask
+        ]
+        return scene

supervision/annotators/utils.py

@@ -8,18 +8,29 @@ from supervision.draw.color import Color, ColorPalette
 from supervision.geometry.core import Position
 
 
-class ColorMap(Enum):
+class ColorLookup(Enum):
     """
-    Enum for annotator color mapping.
+    Enumeration class to define strategies for mapping colors to annotations.
+
+    This enum supports three different lookup strategies:
+        - `INDEX`: Colors are determined by the index of the detection within the scene.
+        - `CLASS`: Colors are determined by the class label of the detected object.
+        - `TRACK`: Colors are determined by the tracking identifier of the object.
     """
 
     INDEX = "index"
     CLASS = "class"
     TRACK = "track"
 
+    @classmethod
+    def list(cls):
+        return list(map(lambda c: c.value, cls))
+
 
 def resolve_color_idx(
-    detections: Detections, detection_idx: int, color_map: ColorMap = ColorMap.CLASS
+    detections: Detections,
+    detection_idx: int,
+    color_lookup: Union[ColorLookup, np.ndarray] = ColorLookup.CLASS,
 ) -> int:
     if detection_idx >= len(detections):
         raise ValueError(
@@ -27,16 +38,23 @@ def resolve_color_idx(
             f"is out of bounds for detections of length {len(detections)}"
         )
 
-    if color_map == ColorMap.INDEX:
+    if isinstance(color_lookup, np.ndarray):
+        if len(color_lookup) != len(detections):
+            raise ValueError(
+                f"Length of color lookup {len(color_lookup)}"
+                f"does not match length of detections {len(detections)}"
+            )
+        return color_lookup[detection_idx]
+    elif color_lookup == ColorLookup.INDEX:
         return detection_idx
-    elif color_map == ColorMap.CLASS:
+    elif color_lookup == ColorLookup.CLASS:
         if detections.class_id is None:
             raise ValueError(
                 "Could not resolve color by class because"
                 "Detections do not have class_id"
             )
         return detections.class_id[detection_idx]
-    elif color_map == ColorMap.TRACK:
+    elif color_lookup == ColorLookup.TRACK:
         if detections.tracker_id is None:
             raise ValueError(
                 "Could not resolve color by track because"
@@ -45,12 +63,26 @@ def resolve_color_idx(
         return detections.tracker_id[detection_idx]
 
 
-def resolve_color(color: Union[Color, ColorPalette], idx: int) -> Color:
+def get_color_by_index(color: Union[Color, ColorPalette], idx: int) -> Color:
     if isinstance(color, ColorPalette):
         return color.by_idx(idx)
     return color
 
 
+def resolve_color(
+    color: Union[Color, ColorPalette],
+    detections: Detections,
+    detection_idx: int,
+    color_lookup: Union[ColorLookup, np.ndarray] = ColorLookup.CLASS,
+) -> Color:
+    idx = resolve_color_idx(
+        detections=detections,
+        detection_idx=detection_idx,
+        color_lookup=color_lookup,
+    )
+    return get_color_by_index(color=color, idx=idx)
+
+
 class Trace:
     def __init__(
         self,

supervision/classification/core.py

@@ -5,8 +5,6 @@ from typing import Any, Optional, Tuple
 
 import numpy as np
 
-from supervision.utils.internal import deprecated
-
 
 def _validate_class_ids(class_id: Any, n: int) -> None:
     """
@@ -41,41 +39,6 @@ class Classifications:
         _validate_class_ids(self.class_id, n)
         _validate_confidence(self.confidence, n)
 
-    @classmethod
-    @deprecated(
-        """
-        This method is deprecated and removed in 0.16.0 release.
-        Use sv.Classifications.from_ultralytics() instead as it is more generic and
-        can be used for detections from any ultralytics.engine.results.Results Object
-        """
-    )
-    def from_yolov8(cls, yolov8_results) -> Classifications:
-        """
-        Creates a Classifications instance from a
-        [YOLOv8](https://github.com/ultralytics/ultralytics) inference result.
-
-        Args:
-            yolov8_results (ultralytics.yolo.engine.results.Results):
-                The output Results instance from YOLOv8
-
-        Returns:
-            Classifications: A new Classifications object.
-
-        Example:
-            ```python
-            >>> import cv2
-            >>> from ultralytics import YOLO
-            >>> import supervision as sv
-
-            >>> image = cv2.imread(SOURCE_IMAGE_PATH)
-            >>> model = YOLO('yolov8s-cls.pt')
-            >>> result = model(image)[0]
-            >>> classifications = sv.Classifications.from_yolov8(result)
-            ```
-        """
-        confidence = yolov8_results.probs.data.cpu().numpy()
-        return cls(class_id=np.arange(confidence.shape[0]), confidence=confidence)
-
     @classmethod
     def from_ultralytics(cls, ultralytics_results) -> Classifications:
         """
@@ -84,7 +47,7 @@ class Classifications:
 
         Args:
             ultralytics_results (ultralytics.engine.results.Results):
-            The output Results instance from ultralytics model
+                The output Results instance from ultralytics model
 
         Returns:
             Classifications: A new Classifications object.

supervision/dataset/core.py

@@ -165,9 +165,8 @@ class DetectionDataset(BaseDataset):
                 where the images should be saved.
                 If not provided, images will not be saved.
             annotations_directory_path (Optional[str]): The path to
-            the directory where the annotations in
-                PASCAL VOC format should be saved. If not provided,
-                annotations will not be saved.
+                the directory where the annotations in PASCAL VOC format should be
+                saved. If not provided, annotations will not be saved.
             min_image_area_percentage (float): The minimum percentage of
                 detection area relative to
                 the image area for a detection to be included.
@@ -178,7 +177,7 @@ class DetectionDataset(BaseDataset):
                 Argument is used only for segmentation datasets.
             approximation_percentage (float): The percentage of
                 polygon points to be removed from the input polygon,
-            in the range [0, 1). Argument is used only for segmentation datasets.
+                in the range [0, 1). Argument is used only for segmentation datasets.
         """
         if images_directory_path:
             save_dataset_images(
@@ -563,8 +562,7 @@ class ClassificationDataset(BaseDataset):
             split_ratio (float, optional): The ratio of the training
                 set to the entire dataset.
             random_state (int, optional): The seed for the
-                random number generator.
-            This is used for reproducibility.
+                random number generator. This is used for reproducibility.
             shuffle (bool, optional): Whether to shuffle the data before splitting.
 
         Returns:

supervision/detection/core.py

@@ -12,7 +12,6 @@ from supervision.detection.utils import (
     xywh_to_xyxy,
 )
 from supervision.geometry.core import Position
-from supervision.utils.internal import deprecated
 
 
 def _validate_xyxy(xyxy: Any, n: int) -> None:
@@ -185,46 +184,6 @@ class Detections:
             class_id=yolov5_detections_predictions[:, 5].astype(int),
         )
 
-    @classmethod
-    @deprecated(
-        """
-        This method is deprecated and removed in 0.15.0 release.
-        Use sv.Detections.from_ultralytics() instead as it is more generic and
-        can be used for detections from any ultralytics.engine.results.Results Object
-        """
-    )
-    def from_yolov8(cls, yolov8_results) -> Detections:
-        """
-        Creates a Detections instance from a
-        [YOLOv8](https://github.com/ultralytics/ultralytics) inference result.
-
-        Args:
-            yolov8_results (ultralytics.yolo.engine.results.Results):
-                The output Results instance from YOLOv8
-
-        Returns:
-            Detections: A new Detections object.
-
-        Example:
-            ```python
-            >>> import cv2
-            >>> from ultralytics import YOLO
-            >>> import supervision as sv
-
-            >>> image = cv2.imread(SOURCE_IMAGE_PATH)
-            >>> model = YOLO('yolov8s.pt')
-            >>> result = model(image)[0]
-            >>> detections = sv.Detections.from_yolov8(result)
-            ```
-        """
-
-        return cls(
-            xyxy=yolov8_results.boxes.xyxy.cpu().numpy(),
-            confidence=yolov8_results.boxes.conf.cpu().numpy(),
-            class_id=yolov8_results.boxes.cls.cpu().numpy().astype(int),
-            mask=extract_ultralytics_masks(yolov8_results),
-        )
-
     @classmethod
     def from_ultralytics(cls, ultralytics_results) -> Detections:
         """
@@ -296,7 +255,7 @@ class Detections:
             >>> detections = sv.Detections.from_yolo_nas(result)
             ```
         """
-        if np.asarray(yolo_nas_results.bboxes_xyxy).shape[0] == 0:
+        if np.asarray(yolo_nas_results.prediction.bboxes_xyxy).shape[0] == 0:
             return cls.empty()
 
         return cls(
@@ -467,7 +426,7 @@ class Detections:
             >>> detections = sv.Detections.from_roboflow(roboflow_result)
             ```
         """
-        xyxy, confidence, class_id, masks = process_roboflow_result(
+        xyxy, confidence, class_id, masks, trackers = process_roboflow_result(
             roboflow_result=roboflow_result
         )
 
@@ -479,6 +438,7 @@ class Detections:
             confidence=confidence,
             class_id=class_id,
             mask=masks,
+            tracker_id=trackers,
         )
 
     @classmethod

supervision/detection/line_counter.py

@@ -1,4 +1,4 @@
-from typing import Dict, Optional
+from typing import Dict, Optional, Tuple
 
 import cv2
 import numpy as np
@@ -10,37 +10,54 @@ from supervision.geometry.core import Point, Rect, Vector
 
 class LineZone:
     """
-    Count the number of objects that cross a line.
+    This class is responsible for counting the number of objects that cross a
+    predefined line.
+
+    !!! warning
+
+        LineZone utilizes the `tracker_id`. Read
+        [here](https://supervision.roboflow.com/trackers/) to learn how to plug
+        tracking into your inference pipeline.
+
+    Attributes:
+        in_count (int): The number of objects that have crossed the line from outside
+            to inside.
+        out_count (int): The number of objects that have crossed the line from inside
+            to outside.
     """
 
     def __init__(self, start: Point, end: Point):
         """
-        Initialize a LineCounter object.
-
-        Attributes:
+        Args:
             start (Point): The starting point of the line.
             end (Point): The ending point of the line.
-
         """
         self.vector = Vector(start=start, end=end)
         self.tracker_state: Dict[str, bool] = {}
         self.in_count: int = 0
         self.out_count: int = 0
 
-    def trigger(self, detections: Detections):
+    def trigger(self, detections: Detections) -> Tuple[np.ndarray, np.ndarray]:
         """
-        Update the in_count and out_count for the detections that cross the line.
+        Update the `in_count` and `out_count` based on the objects that cross the line.
 
-        Attributes:
-            detections (Detections): The detections for which to update the counts.
+        Args:
+            detections (Detections): A list of detections for which to update the
+                counts.
 
+        Returns:
+            A tuple of two boolean NumPy arrays. The first array indicates which
+                detections have crossed the line from outside to inside. The second
+                array indicates which detections have crossed the line from inside to
+                outside.
         """
-        for xyxy, _, confidence, class_id, tracker_id in detections:
-            # handle detections with no tracker_id
+        crossed_in = np.full(len(detections), False)
+        crossed_out = np.full(len(detections), False)
+
+        for i, (xyxy, _, confidence, class_id, tracker_id) in enumerate(detections):
             if tracker_id is None:
                 continue
 
-            # we check if all four anchors of bbox are on the same side of vector
             x1, y1, x2, y2 = xyxy
             anchors = [
                 Point(x=x1, y=y1),
@@ -50,25 +67,27 @@ class LineZone:
             ]
             triggers = [self.vector.is_in(point=anchor) for anchor in anchors]
 
-            # detection is partially in and partially out
             if len(set(triggers)) == 2:
                 continue
 
             tracker_state = triggers[0]
-            # handle new detection
+
             if tracker_id not in self.tracker_state:
                 self.tracker_state[tracker_id] = tracker_state
                 continue
 
-            # handle detection on the same side of the line
             if self.tracker_state.get(tracker_id) == tracker_state:
                 continue
 
             self.tracker_state[tracker_id] = tracker_state
             if tracker_state:
                 self.in_count += 1
+                crossed_in[i] = True
             else:
                 self.out_count += 1
+                crossed_out[i] = True
+
+        return crossed_in, crossed_out
 
 
 class LineZoneAnnotator:

supervision/detection/utils.py

@@ -333,14 +333,15 @@ def extract_ultralytics_masks(yolov8_results) -> Optional[np.ndarray]:
 
 def process_roboflow_result(
     roboflow_result: dict,
-) -> Tuple[np.ndarray, np.ndarray, np.ndarray, Optional[np.ndarray]]:
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray, Optional[np.ndarray], np.ndarray]:
     if not roboflow_result["predictions"]:
-        return np.empty((0, 4)), np.empty(0), np.empty(0), None
+        return np.empty((0, 4)), np.empty(0), np.empty(0), None, None
 
     xyxy = []
     confidence = []
     class_id = []
     masks = []
+    tracker_ids = []
 
     image_width = int(roboflow_result["image"]["width"])
     image_height = int(roboflow_result["image"]["height"])
@@ -359,6 +360,8 @@ def process_roboflow_result(
             xyxy.append([x_min, y_min, x_max, y_max])
             class_id.append(prediction["class_id"])
             confidence.append(prediction["confidence"])
+            if "tracker_id" in prediction:
+                tracker_ids.append(prediction["tracker_id"])
         elif len(prediction["points"]) >= 3:
             polygon = np.array(
                 [[point["x"], point["y"]] for point in prediction["points"]], dtype=int
@@ -368,13 +371,16 @@ def process_roboflow_result(
             class_id.append(prediction["class_id"])
             confidence.append(prediction["confidence"])
             masks.append(mask)
+            if "tracker_id" in prediction:
+                tracker_ids.append(prediction["tracker_id"])
 
     xyxy = np.array(xyxy) if len(xyxy) > 0 else np.empty((0, 4))
     confidence = np.array(confidence) if len(confidence) > 0 else np.empty(0)
     class_id = np.array(class_id).astype(int) if len(class_id) > 0 else np.empty(0)
     masks = np.array(masks, dtype=bool) if len(masks) > 0 else None
+    tracker_id = np.array(tracker_ids).astype(int) if len(tracker_ids) > 0 else None
 
-    return xyxy, confidence, class_id, masks
+    return xyxy, confidence, class_id, masks, tracker_id
 
 
 def move_boxes(xyxy: np.ndarray, offset: np.ndarray) -> np.ndarray:

supervision/draw/color.py

@@ -4,6 +4,7 @@ from dataclasses import dataclass
 from typing import List, Tuple
 
 DEFAULT_COLOR_PALETTE = [
+    "#a351fb",
     "#e6194b",
     "#3cb44b",
     "#ffe119",
@@ -33,21 +34,35 @@ def _validate_color_hex(color_hex: str):
 
 @dataclass
 class Color:
+    """
+    Represents a color in RGB format.
+
+    Attributes:
+        r (int): Red channel.
+        g (int): Green channel.
+        b (int): Blue channel.
+    """
+
     r: int
     g: int
     b: int
 
     @classmethod
-    def from_hex(cls, color_hex: str):
+    def from_hex(cls, color_hex: str) -> Color:
         """
-        Creates a Color instance from a color hex string
+        Create a Color instance from a hex string.
 
-        :param color_hex: str : The color hex string in the format
-            of "fff", "ffffff", "#fff", or "#ffffff"
-        :return: Color : A Color instance representing the color
+        Args:
+            color_hex (str): Hex string of the color.
+
+        Returns:
+            Color: Instance representing the color.
 
         Example:
-        color = Color.from_hex('#ff00ff')
+            ```
+            >>> Color.from_hex('#ff00ff')
+            Color(r=255, g=0, b=255)
+            ```
         """
         _validate_color_hex(color_hex)
         color_hex = color_hex.lstrip("#")
@@ -58,17 +73,31 @@ class Color:
 
     def as_rgb(self) -> Tuple[int, int, int]:
         """
-        Returns the color as a tuple of integers in the RGB format
+        Returns the color as an RGB tuple.
 
-        :return: Tuple[int, int, int] : The color in the RGB format
+        Returns:
+            Tuple[int, int, int]: RGB tuple.
+
+        Example:
+            ```
+            >>> color.as_rgb()
+            (255, 0, 255)
+            ```
         """
         return self.r, self.g, self.b
 
     def as_bgr(self) -> Tuple[int, int, int]:
         """
-        Returns the color as a tuple of integers in the BGR format
+        Returns the color as a BGR tuple.
 
-        :return: Tuple[int, int, int] : The color in the BGR format
+        Returns:
+            Tuple[int, int, int]: BGR tuple.
+
+        Example:
+            ```
+            >>> color.as_bgr()
+            (255, 0, 255)
+            ```
         """
         return self.b, self.g, self.r
 
@@ -99,33 +128,55 @@ class ColorPalette:
 
     @classmethod
     def default(cls) -> ColorPalette:
+        """
+        Returns a default color palette.
+
+        Returns:
+            ColorPalette: A ColorPalette instance with default colors.
+
+        Example:
+            ```
+            >>> ColorPalette.default()
+            ColorPalette(colors=[Color(r=255, g=0, b=0), Color(r=0, g=255, b=0), ...])
+            ```
+        """
         return ColorPalette.from_hex(color_hex_list=DEFAULT_COLOR_PALETTE)
 
     @classmethod
-    def from_hex(cls, color_hex_list: List[str]):
+    def from_hex(cls, color_hex_list: List[str]) -> ColorPalette:
         """
-        Creates a ColorPalette instance from a list of color hex strings
+        Create a ColorPalette instance from a list of hex strings.
 
-        :param color_hex_list: List[str] : A list of color hex strings in the
-            format of "fff", "ffffff", "#fff", or "#ffffff"
-        :return: ColorPalette : A ColorPalette instance representing the color palette
+        Args:
+            color_hex_list (List[str]): List of color hex strings.
+
+        Returns:
+            ColorPalette: A ColorPalette instance.
 
         Example:
-        color_palette = ColorPalette.from_hex(['#ff0000', '#00ff00', '#0000ff'])
+            ```
+            >>> ColorPalette.from_hex(['#ff0000', '#00ff00', '#0000ff'])
+            ColorPalette(colors=[Color(r=255, g=0, b=0), Color(r=0, g=255, b=0), ...])
+            ```
         """
         colors = [Color.from_hex(color_hex) for color_hex in color_hex_list]
         return cls(colors)
 
     def by_idx(self, idx: int) -> Color:
         """
-        Returns the color at a given index in the color palette.
+        Return the color at a given index in the palette.
 
-        :param idx: int : The index of the color in the color palette
-        :return: Color : The color at the given index
+        Args:
+            idx (int): Index of the color in the palette.
+
+        Returns:
+            Color: Color at the given index.
 
         Example:
-        color_palette = ColorPalette.from_hex(['#ff0000', '#00ff00', '#0000ff'])
-        color = color_palette.by_idx(1)
+            ```
+            >>> color_palette.by_idx(1)
+            Color(r=0, g=255, b=0)
+            ```
         """
         if idx < 0:
             raise ValueError("idx argument should not be negative")

supervision/draw/utils.py

@@ -1,4 +1,5 @@
-from typing import Optional
+import os
+from typing import Optional, Union
 
 import cv2
 import numpy as np
@@ -168,3 +169,65 @@ def draw_text(
         lineType=cv2.LINE_AA,
     )
     return scene
+
+
+def draw_image(
+    scene: np.ndarray, image: Union[str, np.ndarray], opacity: float, rect: Rect
+) -> np.ndarray:
+    """
+    Draws an image onto a given scene with specified opacity and dimensions.
+
+    Args:
+        scene (np.ndarray): Background image where the new image will be drawn.
+        image (Union[str, np.ndarray]): Image to draw.
+        opacity (float): Opacity of the image to be drawn.
+        rect (Rect): Rectangle specifying where to draw the image.
+
+    Returns:
+        np.ndarray: The updated scene.
+
+    Raises:
+        FileNotFoundError: If the image path does not exist.
+        ValueError: For invalid opacity or rectangle dimensions.
+    """
+
+    # Validate and load image
+    if isinstance(image, str):
+        if not os.path.exists(image):
+            raise FileNotFoundError(f"Image path ('{image}') does not exist.")
+        image = cv2.imread(image, cv2.IMREAD_UNCHANGED)
+
+    # Validate opacity
+    if not 0.0 <= opacity <= 1.0:
+        raise ValueError("Opacity must be between 0.0 and 1.0.")
+
+    # Validate rectangle dimensions
+    if (
+        rect.x < 0
+        or rect.y < 0
+        or rect.x + rect.width > scene.shape[1]
+        or rect.y + rect.height > scene.shape[0]
+    ):
+        raise ValueError("Invalid rectangle dimensions.")
+
+    # Resize and isolate alpha channel
+    image = cv2.resize(image, (rect.width, rect.height))
+    alpha_channel = (
+        image[:, :, 3]
+        if image.shape[2] == 4
+        else np.ones((rect.height, rect.width), dtype=image.dtype) * 255
+    )
+    alpha_scaled = cv2.convertScaleAbs(alpha_channel * opacity)
+
+    # Perform blending
+    scene_roi = scene[rect.y : rect.y + rect.height, rect.x : rect.x + rect.width]
+    alpha_float = alpha_scaled.astype(np.float32) / 255.0
+    blended_roi = cv2.convertScaleAbs(
+        (1 - alpha_float[..., np.newaxis]) * scene_roi
+        + alpha_float[..., np.newaxis] * image[:, :, :3]
+    )
+
+    # Update the scene
+    scene[rect.y : rect.y + rect.height, rect.x : rect.x + rect.width] = blended_roi
+
+    return scene

supervision/tracker/byte_tracker/core.py

@@ -249,6 +249,8 @@ class ByteTrack:
             detections.confidence = np.array(
                 [t.score for t in tracks], dtype=np.float32
             )
+        else:
+            detections.tracker_id = np.array([], dtype=int)
 
         return detections
 

supervision/utils/video.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import time
+from collections import deque
 from dataclasses import dataclass
 from typing import Callable, Generator, Optional, Tuple
 
@@ -71,13 +73,11 @@ class VideoSink:
         ```python
         >>> import supervision as sv
 
-        >>> video_info = sv.VideoInfo.from_video_path(video_path='source_video.mp4')
+        >>> video_info = sv.VideoInfo.from_video_path('source.mp4')
+        >>> frames_generator = get_video_frames_generator('source.mp4')
 
-        >>> with sv.VideoSink(target_path='target_video.mp4',
-        ...                   video_info=video_info,
-                              codec='H264') as sink:
-        ...     for frame in get_video_frames_generator(source_path='source_video.mp4',
-        ...                                             stride=2):
+        >>> with sv.VideoSink(target_path='target.mp4', video_info=video_info) as sink:
+        ...     for frame in frames_generator:
         ...         sink.write_frame(frame=frame)
         ```
     """
@@ -202,3 +202,55 @@ def process_video(
         ):
             result_frame = callback(frame, index)
             sink.write_frame(frame=result_frame)
+
+
+class FPSMonitor:
+    """
+    A class for monitoring frames per second (FPS) to benchmark latency.
+    """
+
+    def __init__(self, sample_size: int = 30):
+        """
+        Args:
+            sample_size (int): The maximum number of observations for latency
+                benchmarking.
+
+        Examples:
+            ```python
+            >>> import supervision as sv
+
+            >>> frames_generator = sv.get_video_frames_generator('source.mp4')
+            >>> fps_monitor = sv.FPSMonitor()
+
+            >>> for frame in frames_generator:
+            ...     # your processing code here
+            ...     fps_monitor.tick()
+            ...     fps = fps_monitor()
+            ```
+        """
+        self.all_timestamps = deque(maxlen=sample_size)
+
+    def __call__(self) -> float:
+        """
+        Computes and returns the average FPS based on the stored time stamps.
+
+        Returns:
+            float: The average FPS. Returns 0.0 if no time stamps are stored.
+        """
+
+        if not self.all_timestamps:
+            return 0.0
+        taken_time = self.all_timestamps[-1] - self.all_timestamps[0]
+        return (len(self.all_timestamps)) / taken_time if taken_time != 0 else 0.0
+
+    def tick(self) -> None:
+        """
+        Adds a new time stamp to the deque for FPS calculation.
+        """
+        self.all_timestamps.append(time.monotonic())
+
+    def reset(self) -> None:
+        """
+        Clears all the time stamps from the deque.
+        """
+        self.all_timestamps.clear()

test/annotators/test_utils.py

@@ -2,14 +2,15 @@ from contextlib import ExitStack as DoesNotRaise
 from test.utils import mock_detections
 from typing import Optional
 
+import numpy as np
 import pytest
 
-from supervision.annotators.utils import ColorMap, resolve_color_idx
+from supervision.annotators.utils import ColorLookup, resolve_color_idx
 from supervision.detection.core import Detections
 
 
 @pytest.mark.parametrize(
-    "detections, detection_idx, color_map, expected_result, exception",
+    "detections, detection_idx, color_lookup, expected_result, exception",
     [
         (
             mock_detections(
@@ -18,10 +19,10 @@ from supervision.detection.core import Detections
                 tracker_id=[2, 6],
             ),
             0,
-            ColorMap.INDEX,
+            ColorLookup.INDEX,
             0,
             DoesNotRaise(),
-        ),  # multiple detections; index mapping
+        ),  # multiple detections; index lookup
         (
             mock_detections(
                 xyxy=[[10, 10, 20, 20], [20, 20, 30, 30]],
@@ -29,10 +30,10 @@ from supervision.detection.core import Detections
                 tracker_id=[2, 6],
             ),
             0,
-            ColorMap.CLASS,
+            ColorLookup.CLASS,
             5,
             DoesNotRaise(),
-        ),  # multiple detections; class mapping
+        ),  # multiple detections; class lookup
         (
             mock_detections(
                 xyxy=[[10, 10, 20, 20], [20, 20, 30, 30]],
@@ -40,17 +41,17 @@ from supervision.detection.core import Detections
                 tracker_id=[2, 6],
             ),
             0,
-            ColorMap.TRACK,
+            ColorLookup.TRACK,
             2,
             DoesNotRaise(),
-        ),  # multiple detections; track mapping
+        ),  # multiple detections; track lookup
         (
             Detections.empty(),
             0,
-            ColorMap.INDEX,
+            ColorLookup.INDEX,
             None,
             pytest.raises(ValueError),
-        ),  # no detections; index mapping; out of bounds
+        ),  # no detections; index lookup; out of bounds
         (
             mock_detections(
                 xyxy=[[10, 10, 20, 20], [20, 20, 30, 30]],
@@ -58,30 +59,44 @@ from supervision.detection.core import Detections
                 tracker_id=[2, 6],
             ),
             2,
-            ColorMap.INDEX,
+            ColorLookup.INDEX,
             None,
             pytest.raises(ValueError),
-        ),  # multiple detections; index mapping; out of bounds
+        ),  # multiple detections; index lookup; out of bounds
         (
             mock_detections(xyxy=[[10, 10, 20, 20], [20, 20, 30, 30]]),
             0,
-            ColorMap.CLASS,
+            ColorLookup.CLASS,
             None,
             pytest.raises(ValueError),
-        ),  # multiple detections; class mapping; no class_id
+        ),  # multiple detections; class lookup; no class_id
         (
             mock_detections(xyxy=[[10, 10, 20, 20], [20, 20, 30, 30]]),
             0,
-            ColorMap.TRACK,
+            ColorLookup.TRACK,
             None,
             pytest.raises(ValueError),
-        ),  # multiple detections; class mapping; no track_id
+        ),  # multiple detections; class lookup; no track_id
+        (
+            mock_detections(xyxy=[[10, 10, 20, 20], [20, 20, 30, 30]]),
+            0,
+            np.array([1, 0]),
+            1,
+            DoesNotRaise(),
+        ),  # multiple detections; custom lookup; correct length
+        (
+            mock_detections(xyxy=[[10, 10, 20, 20], [20, 20, 30, 30]]),
+            0,
+            np.array([1]),
+            None,
+            pytest.raises(ValueError),
+        ),  # multiple detections; custom lookup; wrong length
     ],
 )
 def test_resolve_color_idx(
     detections: Detections,
     detection_idx: int,
-    color_map: ColorMap,
+    color_lookup: ColorLookup,
     expected_result: Optional[int],
     exception: Exception,
 ) -> None:
@@ -89,6 +104,6 @@ def test_resolve_color_idx(
         result = resolve_color_idx(
             detections=detections,
             detection_idx=detection_idx,
-            color_map=color_map,
+            color_lookup=color_lookup,
         )
         assert result == expected_result

test/detection/test_utils.py

@@ -264,7 +264,7 @@ def test_filter_polygons_by_area(
     [
         (
             {"predictions": [], "image": {"width": 1000, "height": 1000}},
-            (np.empty((0, 4)), np.empty(0), np.empty(0), None),
+            (np.empty((0, 4)), np.empty(0), np.empty(0), None, None),
             DoesNotRaise(),
         ),  # empty result
         (
@@ -287,6 +287,7 @@ def test_filter_polygons_by_area(
                 np.array([0.9]),
                 np.array([0]),
                 None,
+                None,
             ),
             DoesNotRaise(),
         ),  # single correct object detection result
@@ -301,6 +302,7 @@ def test_filter_polygons_by_area(
                         "confidence": 0.9,
                         "class_id": 0,
                         "class": "person",
+                        "tracker_id": 1,
                     },
                     {
                         "x": 500.0,
@@ -310,6 +312,7 @@ def test_filter_polygons_by_area(
                         "confidence": 0.8,
                         "class_id": 7,
                         "class": "truck",
+                        "tracker_id": 2,
                     },
                 ],
                 "image": {"width": 1000, "height": 1000},
@@ -319,6 +322,7 @@ def test_filter_polygons_by_area(
                 np.array([0.9, 0.8]),
                 np.array([0, 7]),
                 None,
+                np.array([1, 2]),
             ),
             DoesNotRaise(),
         ),  # two correct object detection result
@@ -334,11 +338,12 @@ def test_filter_polygons_by_area(
                         "class_id": 0,
                         "class": "person",
                         "points": [],
+                        "tracker_id": None,
                     }
                 ],
                 "image": {"width": 1000, "height": 1000},
             },
-            (np.empty((0, 4)), np.empty(0), np.empty(0), None),
+            (np.empty((0, 4)), np.empty(0), np.empty(0), None, None),
             DoesNotRaise(),
         ),  # single incorrect instance segmentation result with no points
         (
@@ -357,7 +362,7 @@ def test_filter_polygons_by_area(
                 ],
                 "image": {"width": 1000, "height": 1000},
             },
-            (np.empty((0, 4)), np.empty(0), np.empty(0), None),
+            (np.empty((0, 4)), np.empty(0), np.empty(0), None, None),
             DoesNotRaise(),
         ),  # single incorrect instance segmentation result with no enough points
         (
@@ -386,6 +391,7 @@ def test_filter_polygons_by_area(
                 np.array([0.9]),
                 np.array([0]),
                 TEST_MASK,
+                None,
             ),
             DoesNotRaise(),
         ),  # single incorrect instance segmentation result with no enough points
@@ -425,6 +431,7 @@ def test_filter_polygons_by_area(
                 np.array([0.9]),
                 np.array([0]),
                 TEST_MASK,
+                None,
             ),
             DoesNotRaise(),
         ),  # two instance segmentation results - one correct, one incorrect
@@ -432,7 +439,9 @@ def test_filter_polygons_by_area(
 )
 def test_process_roboflow_result(
     roboflow_result: dict,
-    expected_result: Tuple[np.ndarray, np.ndarray, np.ndarray, Optional[np.ndarray]],
+    expected_result: Tuple[
+        np.ndarray, np.ndarray, np.ndarray, Optional[np.ndarray], np.ndarray
+    ],
     exception: Exception,
 ) -> None:
     with exception:
@@ -443,6 +452,9 @@ def test_process_roboflow_result(
         assert (result[3] is None and expected_result[3] is None) or (
             np.array_equal(result[3], expected_result[3])
         )
+        assert (result[4] is None and expected_result[4] is None) or (
+            np.array_equal(result[4], expected_result[4])
+        )
 
 
 @pytest.mark.parametrize(