Merge pull request #1258 from roboflow/develop

`supervision-0.21.0` release

.github/workflows/publish-dev-docs.yml

@@ -4,12 +4,18 @@ on:
   push:
     branches:
       - develop
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.ref}}
+  cancel-in-progress: true
 
 permissions:
   contents: write
   pages: write
   pull-requests: write
 
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -21,19 +27,27 @@ jobs:
       - name: 🐍 Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.x
+          python-version: '3.10'
       - name: 📦 Install mkdocs-material
-        run: pip install mkdocs-material
+        run: pip install "mkdocs-material"
       - name: 📦 Install mkdocstrings[python]
         run: pip install "mkdocstrings[python]"
       - name: 📦 Install mkdocs-material[imaging]
         run: pip install "mkdocs-material[imaging]"
       - name: 📦 Install mike
         run: pip install "mike"
+      - name: 📦 Install mkdocs-git-revision-date-localized-plugin
+        run: pip install "mkdocs-git-revision-date-localized-plugin"
+      - name: 📦 Install JupyterLab
+        run: pip install jupyterlab
+      - name: 📦 Install mkdocs-jupyter
+        run: pip install mkdocs-jupyter
+      - name: 📦 Install mkdocs-git-committers-plugin-2
+        run: pip install mkdocs-git-committers-plugin-2
       - name: ⚙️ Configure git for github-actions
         run: |
           git config --global user.name "github-actions[bot]"
           git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
       - name: 🚀 Deploy MkDoc-Material with mike
         run: |
-          mike deploy --push develop
+          MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} mike deploy --push develop

.github/workflows/publish-release-docs.yml

@@ -0,0 +1,55 @@
+name: Supervision Release Documentation Workflow 📚
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.ref}}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pages: write
+  pull-requests: write
+
+
+jobs:
+  doc-build-deploy:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+    steps:
+      - name: 🛎️ Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.head_ref }}
+
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: 📦 Install mkdocs-material
+        run: pip install "mkdocs-material"
+      - name: 📦 Install mkdocstrings[python]
+        run: pip install "mkdocstrings[python]"
+      - name: 📦 Install mkdocs-material[imaging]
+        run: pip install "mkdocs-material[imaging]"
+      - name: 📦 Install mike
+        run: pip install "mike"
+      - name: 📦 Install mkdocs-git-revision-date-localized-plugin
+        run: pip install "mkdocs-git-revision-date-localized-plugin"
+      - name: 📦 Install JupyterLab
+        run: pip install jupyterlab
+      - name: 📦 Install mkdocs-jupyter
+        run: pip install mkdocs-jupyter
+      - name: 📦 Install mkdocs-git-committers-plugin-2
+        run: pip install mkdocs-git-committers-plugin-2
+      - name: ⚙️ Configure git for github-actions 👷
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: 🚀 Deploy MkDoc-Material 📚
+        run: |
+            latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`)
+            MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} mike deploy --push --update-aliases $latest_tag latest

.github/workflows/publish-test.yml

@@ -6,22 +6,24 @@ on:
       - '[0-9]+.[0-9]+[0-9]+.[0-9]+b[0-9]'
       - '[0-9]+.[0-9]+[0-9]+.[0-9]+rc[0-9]'
 
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
 jobs:
   build-n-publish:
     name: Build and publish to PyPI
     runs-on: ubuntu-latest
-
+    strategy:
+      matrix:
+        python-version: ["3.10"]
     steps:
-      - name: Checkout source
+      - name: 🛎️ Checkout
         uses: actions/checkout@v4
-
-      - name: 🐍 Set up Python 3.8 environment for build
+        with:
+          ref: ${{ github.head_ref }}
+      - name: 🐍 Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: "3.8"
+          python-version: ${{ matrix.python-version }}
 
       - name: 🏗️ Build source and wheel distributions
         run: |

.github/workflows/publish.yml

@@ -3,10 +3,7 @@ on:
   push:
     tags:
       - '[0-9]+.[0-9]+[0-9]+.[0-9]'
-      - '[0-9]+.[0-9]+[0-9]+.[0-9]'
-      - '[0-9]+.[0-9]+[0-9]+.[0-9]'
 
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
 jobs:
@@ -14,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.8]
+        python-version: ["3.10"]
     steps:
       - name: 🛎️ Checkout
         uses: actions/checkout@v4

.github/workflows/test-doc.yml

@@ -0,0 +1,34 @@
+name: 🧪 Docs Test WorkFlow 📚
+
+on:
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  docs-build-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🔄 Checkout code
+        uses: actions/checkout@v4
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: 📦 Install mkdocs-material
+        run: pip install "mkdocs-material[all]"
+      - name: 📦 Install mkdocstrings[python]
+        run: pip install "mkdocstrings[python]"
+      - name: 📦 Install mkdocs-material[imaging]
+        run: pip install "mkdocs-material[imaging]"
+      - name: 📦 Install mike
+        run: pip install "mike"
+      - name: 📦 Install mkdocs-git-revision-date-localized-plugin
+        run: pip install "mkdocs-git-revision-date-localized-plugin"
+      - name: 📦 Install JupyterLab
+        run: pip install jupyterlab
+      - name: 📦 Install mkdocs-jupyter
+        run: pip install mkdocs-jupyter
+      - name: 📦 Install mkdocs-git-committers-plugin-2
+        run: pip install mkdocs-git-committers-plugin-2
+      - name: 🧪 Test documentation build
+        run: mkdocs build --verbose

.github/workflows/test-min.yml

@@ -37,6 +37,7 @@ jobs:
               matplotlib==3.5.0 \
               numpy==1.21.2 \
               opencv-python==4.5.5.64 \
+              Pillow==10.1.0 \
               packaging==23.2 \
               pluggy==1.3.0 \
               pyparsing==3.1.1 \

.gitignore

@@ -133,9 +133,6 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
-# Notebooks
-notebooks/
-
 # OSX folder attributes
 .DS_Store
 .AppleDouble

.pre-commit-config.yaml

@@ -7,14 +7,13 @@ ci:
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace
         exclude: test/.*\.py
       - id: check-yaml
         exclude: mkdocs.yml
-      - id: check-docstring-first
       - id: check-executables-have-shebangs
       - id: check-toml
       - id: check-case-conflict
@@ -28,9 +27,8 @@ repos:
       - id: mixed-line-ending
 
 
-
   -   repo: https://github.com/PyCQA/bandit
-      rev: '1.7.7'
+      rev: '1.7.8'
       hooks:
       -   id: bandit
           args: ["-c", "pyproject.toml"]
@@ -47,7 +45,7 @@ repos:
 
 
   -   repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.2.0
+      rev: v0.4.7
       hooks:
       -   id: ruff
           args: [--fix, --exit-non-zero-on-fix]

CONTRIBUTING.md

@@ -112,6 +112,20 @@ To run the documentation, install the project requirements with `poetry install
 
 You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/).
 
+## 🧑‍🍳 cookbooks
+
+We are always looking for new examples and cookbooks to add to the `supervision`
+documentation. If you have a use case that you think would be helpful to others, please
+submit a PR with your example. Here are some guidelines for submitting a new example:
+
+- Create a new notebook in the [`docs/nodebooks`](https://github.com/roboflow/supervision/tree/develop/docs/notebooks) folder.
+- Add a link to the new notebook in [`docs/theme/cookbooks.html`](https://github.com/roboflow/supervision/blob/develop/docs/theme/cookbooks.html). Make sure to add the path to the new notebook, as well as a title, labels, author and supervision version.
+- Use the [Count Objects Crossing the Line](https://supervision.roboflow.com/develop/notebooks/count-objects-crossing-the-line/) example as a template for your new example.
+- Freeze the version of `supervision` you are using.
+- Place an appropriate Open in Colab button at the top of the notebook. You can find an example of such a button in the aforementioned `Count Objects Crossing the Line` cookbook.
+- Notebook should be self-contained. If you rely on external data ( videos, images, etc.) or libraries, include download and installation commands in the notebook.
+- Annotate the code with appropriate comments, including links to the documentation describing each of the tools you have used.
+
 ## 🧪 tests
 
 [`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests.

README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <p>
-    <a align="center" href="" target="_blank">
+    <a align="center" href="" target="https://supervision.roboflow.com">
       <img
         width="100%"
         src="https://media.roboflow.com/open-source/supervision/rf-supervision-banner.png?updatedAt=1678995927529"
@@ -10,7 +10,7 @@
 
   <br>
 
-[notebooks](https://github.com/roboflow/notebooks) | [inference](https://github.com/roboflow/inference) | [autodistill](https://github.com/autodistill/autodistill) | [collect](https://github.com/roboflow/roboflow-collect)
+[notebooks](https://github.com/roboflow/notebooks) | [inference](https://github.com/roboflow/inference) | [autodistill](https://github.com/autodistill/autodistill) | [maestro](https://github.com/roboflow/multimodal-maestro)
 
   <br>
 
@@ -18,16 +18,18 @@
 [![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision)
 [![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)
-
+[![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)
+[![built-with-material-for-mkdocs](https://img.shields.io/badge/Material_for_MkDocs-526CFE?logo=MaterialForMkDocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)
 </div>
 
 ## 👋 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! 🤝
 
+[![supervision-hackfest](https://github.com/roboflow/supervision/assets/26109316/c05cc954-b9a6-4ed5-9a52-d0b4b619ff65)](https://github.com/orgs/roboflow/projects/10)
+
 ## 💻 install
 
 Pip install the supervision package in a
@@ -37,7 +39,7 @@ Pip install the supervision package in a
 pip install supervision
 ```
 
-Read more about desktop, headless, and local installation in our [guide](https://roboflow.github.io/supervision/).
+Read more about conda, mamba, and installing from source in our [guide](https://roboflow.github.io/supervision/).
 
 ## 🔥 quickstart
 
@@ -69,16 +71,15 @@ len(detections)
     ```python
     import cv2
     import supervision as sv
-    from inference.models.utils import get_roboflow_model
+    from inference import get_model
 
     image = cv2.imread(...)
-    model = get_roboflow_model(model_id="yolov8s-640", api_key=<ROBOFLOW API KEY>)
+    model = get_model(model_id="yolov8s-640", api_key=<ROBOFLOW API KEY>)
     result = model.infer(image)[0]
     detections = sv.Detections.from_inference(result)
 
     len(detections)
-    # 5
-
+    # 5
     ```
 
 </details>
@@ -215,19 +216,23 @@ len(dataset)
 
 ## 🎬 tutorials
 
-<p align="left">
-<a href="https://youtu.be/uWP6UjDeZvY" title="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source"><img src="https://github.com/SkalskiP/SkalskiP/assets/26109316/61a444c8-b135-48ce-b979-2a5ab47c5a91" alt="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source" width="300px" align="left" /></a>
-<a href="https://youtu.be/uWP6UjDeZvY" title="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source"><strong>Speed Estimation & Vehicle Tracking | Computer Vision | Open Source</strong></a>
-<div><strong>Created: 11 Jan 2024</strong> | <strong>Updated: 11 Jan 2024</strong></div>
-<br/> Learn how to track and estimate the speed of vehicles using YOLO, ByteTrack, and Roboflow Inference. This comprehensive tutorial covers object detection, multi-object tracking, filtering detections, perspective transformation, speed estimation, visualization improvements, and more.</p>
+Want to learn how to use Supervision? Explore our [how-to guides](https://supervision.roboflow.com/develop/how_to/detect_and_annotate/), [end-to-end examples](https://github.com/roboflow/supervision/tree/develop/examples), and [cookbooks](https://supervision.roboflow.com/develop/cookbooks/)!
 
 <br/>
 
 <p align="left">
-<a href="https://youtu.be/4Q3ut7vqD5o" title="Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking"><img src="https://github.com/roboflow/supervision/assets/26109316/54afdf1c-218c-4451-8f12-627fb85f1682" alt="Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking" width="300px" align="left" /></a>
-<a href="https://youtu.be/4Q3ut7vqD5o" title="Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking"><strong>Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking</strong></a>
-<div><strong>Created: 6 Sep 2023</strong> | <strong>Updated: 6 Sep 2023</strong></div>
-<br/> In this video, we explore real-time traffic analysis using YOLOv8 and ByteTrack to detect and track vehicles on aerial images. Harnessing the power of Python and Supervision, we delve deep into assigning cars to specific entry zones and understanding their direction of movement. By visualizing their paths, we gain insights into traffic flow across bustling roundabouts... </p>
+<a href="https://youtu.be/hAWpsIuem10" title="Dwell Time Analysis with Computer Vision | Real-Time Stream Processing"><img src="https://github.com/SkalskiP/SkalskiP/assets/26109316/a742823d-c158-407d-b30f-063a5d11b4e1" alt="Dwell Time Analysis with Computer Vision | Real-Time Stream Processing" width="300px" align="left" /></a>
+<a href="https://youtu.be/hAWpsIuem10" title="Dwell Time Analysis with Computer Vision | Real-Time Stream Processing"><strong>Dwell Time Analysis with Computer Vision | Real-Time Stream Processing</strong></a>
+<div><strong>Created: 5 Apr 2024</strong></div>
+<br/>Learn how to use computer vision to analyze wait times and optimize processes. This tutorial covers object detection, tracking, and calculating time spent in designated zones. Use these techniques to improve customer experience in retail, traffic management, or other scenarios.</p>
+
+<br/>
+
+<p align="left">
+<a href="https://youtu.be/uWP6UjDeZvY" title="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source"><img src="https://github.com/SkalskiP/SkalskiP/assets/26109316/61a444c8-b135-48ce-b979-2a5ab47c5a91" alt="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source" width="300px" align="left" /></a>
+<a href="https://youtu.be/uWP6UjDeZvY" title="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source"><strong>Speed Estimation & Vehicle Tracking | Computer Vision | Open Source</strong></a>
+<div><strong>Created: 11 Jan 2024</strong></div>
+<br/>Learn how to track and estimate the speed of vehicles using YOLO, ByteTrack, and Roboflow Inference. This comprehensive tutorial covers object detection, multi-object tracking, filtering detections, perspective transformation, speed estimation, visualization improvements, and more.</p>
 
 ## 💜 built with supervision
 

docs/assets.md

@@ -7,8 +7,7 @@ comments: true
 Supervision offers an assets download utility that allows you to download video files
 that you can use in your demos.
 
-## install extra
-
+## Install extra
 
 To install the Supervision assets utility, you can use `pip`. This utility is available
 as an extra within the Supervision package.
@@ -16,17 +15,17 @@ as an extra within the Supervision package.
 !!! example "pip install"
 
     ```bash
-    pip install supervision[assets]
+    pip install "supervision[assets]"
     ```
 
 <div class="md-typeset">
-  <h2>download_assets</h2>
+    <h2><a href="#supervision.assets.downloader.download_assets.download_assets">download_assets</a></h2>
 </div>
 
 :::supervision.assets.downloader.download_assets
 
 <div class="md-typeset">
-  <h2>VideoAssets</h2>
+    <h2><a href="#supervision.assets.downloader.download_assets.VideoAssets">VideoAssets</a></h2>
 </div>
 
 :::supervision.assets.list.VideoAssets

docs/changelog.md

@@ -1,6 +1,233 @@
+### 0.21.0 <small>Jun 5, 2024</small>
+
+- Added [#500](https://github.com/roboflow/supervision/pull/500): [`sv.Detections.with_nmm`](https://supervision.roboflow.com/develop/detection/core/#supervision.detection.core.Detections.with_nmm) to perform non-maximum merging on the current set of object detections.
+
+- Added [#1221](https://github.com/roboflow/supervision/pull/1221): [`sv.Detections.from_lmm`](https://supervision.roboflow.com/develop/detection/core/#supervision.detection.core.Detections.from_lmm) allowing to parse Large Multimodal Model (LMM) text result into [`sv.Detections`](https://supervision.roboflow.com/develop/detection/core/) object. For now `from_lmm` supports only [PaliGemma](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-finetune-paligemma-on-detection-dataset.ipynb) result parsing.
+
+```python
+import supervision as sv
+
+paligemma_result = "<loc0256><loc0256><loc0768><loc0768> cat"
+detections = sv.Detections.from_lmm(
+    sv.LMM.PALIGEMMA,
+    paligemma_result,
+    resolution_wh=(1000, 1000),
+    classes=['cat', 'dog']
+)
+detections.xyxy
+# array([[250., 250., 750., 750.]])
+
+detections.class_id
+# array([0])
+```
+
+- Added [#1236](https://github.com/roboflow/supervision/pull/1236): [`sv.VertexLabelAnnotator`](https://supervision.roboflow.com/develop/keypoint/annotators/#supervision.keypoint.annotators.EdgeAnnotator.annotate) allowing to annotate every vertex of a keypoint skeleton with custom text and color.
+
+```python
+import supervision as sv
+
+image = ...
+key_points = sv.KeyPoints(...)
+
+edge_annotator = sv.EdgeAnnotator(
+    color=sv.Color.GREEN,
+    thickness=5
+)
+annotated_frame = edge_annotator.annotate(
+    scene=image.copy(),
+    key_points=key_points
+)
+```
+
+- Added [#1147](https://github.com/roboflow/supervision/pull/1147): [`sv.KeyPoints.from_inference`](https://supervision.roboflow.com/develop/keypoint/core/#supervision.keypoint.core.KeyPoints.from_inference) allowing to create [`sv.KeyPoints`](https://supervision.roboflow.com/develop/keypoint/core/#supervision.keypoint.core.KeyPoints) from [Inference](https://github.com/roboflow/inference) result.
+
+- Added [#1138](https://github.com/roboflow/supervision/pull/1138): [`sv.KeyPoints.from_yolo_nas`](https://supervision.roboflow.com/develop/keypoint/core/#supervision.keypoint.core.KeyPoints.from_yolo_nas) allowing to create [`sv.KeyPoints`](https://supervision.roboflow.com/develop/keypoint/core/#supervision.keypoint.core.KeyPoints) from [YOLO-NAS](https://github.com/Deci-AI/super-gradients/blob/master/YOLONAS.md) result.
+
+- Added [#1163](https://github.com/roboflow/supervision/pull/1163): [`sv.mask_to_rle`](https://supervision.roboflow.com/develop/datasets/utils/#supervision.dataset.utils.rle_to_mask) and [`sv.rle_to_mask`](https://supervision.roboflow.com/develop/datasets/utils/#supervision.dataset.utils.rle_to_mask) allowing for easy conversion between mask and rle formats.
+
+- Changed [#1236](https://github.com/roboflow/supervision/pull/1236): [`sv.InferenceSlicer`](https://supervision.roboflow.com/develop/detection/tools/inference_slicer/) allowing to select overlap filtering strategy (`NONE`, `NON_MAX_SUPPRESSION` and `NON_MAX_MERGE`).
+
+- Changed [#1178](https://github.com/roboflow/supervision/pull/1178): [`sv.InferenceSlicer`](https://supervision.roboflow.com/develop/detection/tools/inference_slicer/) adding instance segmentation model support.
+
+```python
+import cv2
+import numpy as np
+import supervision as sv
+from inference import get_model
+
+model = get_model(model_id="yolov8x-seg-640")
+image = cv2.imread(<SOURCE_IMAGE_PATH>)
+
+def callback(image_slice: np.ndarray) -> sv.Detections:
+    results = model.infer(image_slice)[0]
+    return sv.Detections.from_inference(results)
+
+slicer = sv.InferenceSlicer(callback = callback)
+detections = slicer(image)
+
+mask_annotator = sv.MaskAnnotator()
+label_annotator = sv.LabelAnnotator()
+
+annotated_image = mask_annotator.annotate(
+    scene=image, detections=detections)
+annotated_image = label_annotator.annotate(
+    scene=annotated_image, detections=detections)
+```
+
+- Changed [#1228](https://github.com/roboflow/supervision/pull/1228): [`sv.LineZone`](https://supervision.roboflow.com/develop/detection/tools/line_zone/) making it 10-20 times faster, depending on the use case.
+
+- Changed [#1163](https://github.com/roboflow/supervision/pull/1163): [`sv.DetectionDataset.from_coco`](https://supervision.roboflow.com/develop/datasets/core/#supervision.dataset.core.DetectionDataset.from_coco) and [`sv.DetectionDataset.as_coco`](https://supervision.roboflow.com/develop/datasets/core/#supervision.dataset.core.DetectionDataset.as_coco) adding support for run-length encoding (RLE) mask format.
+
+### 0.20.0 <small>April 24, 2024</small>
+
+- Added [#1128](https://github.com/roboflow/supervision/pull/1128): [`sv.KeyPoints`](/0.20.0/keypoint/core/#supervision.keypoint.core.KeyPoints) to provide initial support for pose estimation and broader keypoint detection models.
+
+- Added [#1128](https://github.com/roboflow/supervision/pull/1128): [`sv.EdgeAnnotator`](/0.20.0/keypoint/annotators/#supervision.keypoint.annotators.EdgeAnnotator) and [`sv.VertexAnnotator`](/0.20.0/keypoint/annotators/#supervision.keypoint.annotators.VertexAnnotator) to enable rendering of results from keypoint detection models.
+
+```python
+import cv2
+import supervision as sv
+from ultralytics import YOLO
+
+image = cv2.imread(<SOURCE_IMAGE_PATH>)
+model = YOLO('yolov8l-pose')
+
+result = model(image, verbose=False)[0]
+keypoints = sv.KeyPoints.from_ultralytics(result)
+
+edge_annotators = sv.EdgeAnnotator(color=sv.Color.GREEN, thickness=5)
+annotated_image = edge_annotators.annotate(image.copy(), keypoints)
+```
+
+- Changed [#1037](https://github.com/roboflow/supervision/pull/1037): [`sv.LabelAnnotator`](/0.20.0/annotators/#supervision.annotators.core.LabelAnnotator) by adding an additional `corner_radius` argument that allows for rounding the corners of the bounding box.
+
+- Changed [#1109](https://github.com/roboflow/supervision/pull/1109): [`sv.PolygonZone`](/0.20.0/detection/tools/polygon_zone/#supervision.detection.tools.polygon_zone.PolygonZone) such that the `frame_resolution_wh` argument is no longer required to initialize `sv.PolygonZone`.
+
+!!! failure "Deprecated"
+
+    The `frame_resolution_wh` parameter in `sv.PolygonZone` is deprecated and will be removed in `supervision-0.24.0`.
+
+- Changed [#1084](https://github.com/roboflow/supervision/pull/1084): [`sv.get_polygon_center`](/0.20.0/utils/geometry/#supervision.geometry.core.utils.get_polygon_center) to calculate a more accurate polygon centroid.
+
+- Changed [#1069](https://github.com/roboflow/supervision/pull/1069): [`sv.Detections.from_transformers`](/0.20.0/detection/core/#supervision.detection.core.Detections.from_transformers) by adding support for Transformers segmentation models and extract class names values.
+
+```python
+import torch
+import supervision as sv
+from PIL import Image
+from transformers import DetrImageProcessor, DetrForSegmentation
+
+processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50-panoptic")
+model = DetrForSegmentation.from_pretrained("facebook/detr-resnet-50-panoptic")
+
+image = Image.open(<SOURCE_IMAGE_PATH>)
+inputs = processor(images=image, return_tensors="pt")
+
+with torch.no_grad():
+    outputs = model(**inputs)
+
+width, height = image.size
+target_size = torch.tensor([[height, width]])
+results = processor.post_process_segmentation(
+    outputs=outputs, target_sizes=target_size)[0]
+detections = sv.Detections.from_transformers(results, id2label=model.config.id2label)
+
+mask_annotator = sv.MaskAnnotator()
+label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+
+annotated_image = mask_annotator.annotate(
+    scene=image, detections=detections)
+annotated_image = label_annotator.annotate(
+    scene=annotated_image, detections=detections)
+```
+
+- Fixed [#787](https://github.com/roboflow/supervision/pull/787): [`sv.ByteTrack.update_with_detections`](/0.20.0/trackers/#supervision.tracker.byte_tracker.core.ByteTrack.update_with_detections) which was removing segmentation masks while tracking. Now, `ByteTrack` can be used alongside segmentation models.
+
+### 0.19.0 <small>March 15, 2024</small>
+
+- Added [#818](https://github.com/roboflow/supervision/pull/818): [`sv.CSVSink`](/0.19.0/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink) allowing for the straightforward saving of image, video, or stream inference results in a `.csv` file.
+
+```python
+import supervision as sv
+from ultralytics import YOLO
+
+model = YOLO(<SOURCE_MODEL_PATH>)
+csv_sink = sv.CSVSink(<RESULT_CSV_FILE_PATH>)
+frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+with csv_sink:
+    for frame in frames_generator:
+        result = model(frame)[0]
+        detections = sv.Detections.from_ultralytics(result)
+        csv_sink.append(detections, custom_data={<CUSTOM_LABEL>:<CUSTOM_DATA>})
+```
+
+- Added [#819](https://github.com/roboflow/supervision/pull/819): [`sv.JSONSink`](/0.19.0/detection/tools/save_detections/#supervision.detection.tools.csv_sink.JSONSink) allowing for the straightforward saving of image, video, or stream inference results in a `.json` file.
+
+```python
+
+```python
+import supervision as sv
+from ultralytics import YOLO
+
+model = YOLO(<SOURCE_MODEL_PATH>)
+json_sink = sv.JSONSink(<RESULT_JSON_FILE_PATH>)
+frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+with json_sink:
+    for frame in frames_generator:
+        result = model(frame)[0]
+        detections = sv.Detections.from_ultralytics(result)
+        json_sink.append(detections, custom_data={<CUSTOM_LABEL>:<CUSTOM_DATA>})
+```
+
+- Added [#847](https://github.com/roboflow/supervision/pull/847): [`sv.mask_iou_batch`](/0.19.0/detection/utils/#supervision.detection.utils.mask_iou_batch) allowing to compute Intersection over Union (IoU) of two sets of masks.
+
+- Added [#847](https://github.com/roboflow/supervision/pull/847): [`sv.mask_non_max_suppression`](/0.19.0/detection/utils/#supervision.detection.utils.mask_non_max_suppression) allowing to perform Non-Maximum Suppression (NMS) on segmentation predictions.
+
+- Added [#888](https://github.com/roboflow/supervision/pull/888): [`sv.CropAnnotator`](/0.19.0/annotators/#supervision.annotators.core.CropAnnotator) allowing users to annotate the scene with scaled-up crops of detections.
+
+```python
+import cv2
+import supervision as sv
+from inference import get_model
+
+image = cv2.imread(<SOURCE_IMAGE_PATH>)
+model = get_model(model_id="yolov8n-640")
+
+result = model.infer(image)[0]
+detections = sv.Detections.from_inference(result)
+
+crop_annotator = sv.CropAnnotator()
+annotated_frame = crop_annotator.annotate(
+    scene=image.copy(),
+    detections=detections
+)
+```
+
+- Changed [#827](https://github.com/roboflow/supervision/pull/827): [`sv.ByteTrack.reset`](/0.19.0/tracking/#supervision.tracking.ByteTrack.reset) allowing users to clear trackers state, enabling the processing of multiple video files in sequence.
+
+- Changed [#802](https://github.com/roboflow/supervision/pull/802): [`sv.LineZoneAnnotator`](/0.19.0/detection/tools/line_zone/#supervision.detection.line_zone.LineZone) allowing to hide in/out count using `display_in_count` and `display_out_count` properties.
+
+- Changed [#787](https://github.com/roboflow/supervision/pull/787): [`sv.ByteTrack`](/0.19.0/tracking/#supervision.tracking.ByteTrack) input arguments and docstrings updated to improve readability and ease of use.
+
+!!! failure "Deprecated"
+
+    The `track_buffer`, `track_thresh`, and `match_thresh` parameters in `sv.ByterTrack` are deprecated and will be removed in `supervision-0.23.0`. Use `lost_track_buffer,` `track_activation_threshold`, and `minimum_matching_threshold` instead.
+
+- Changed [#910](https://github.com/roboflow/supervision/pull/910): [`sv.PolygonZone`](/0.19.0/detection/tools/polygon_zone/#supervision.detection.tools.polygon_zone.PolygonZone) to now accept a list of specific box anchors that must be in zone for a detection to be counted.
+
+!!! failure "Deprecated"
+
+    The `triggering_position ` parameter in `sv.PolygonZone` is deprecated and will be removed in `supervision-0.23.0`. Use `triggering_anchors` instead.
+
+- Changed [#875](https://github.com/roboflow/supervision/pull/875): annotators adding support for Pillow images. All supervision Annotators can now accept an image as either a numpy array or a Pillow Image. They automatically detect its type, draw annotations, and return the output in the same format as the input.
+
+- Fixed [#944](https://github.com/roboflow/supervision/pull/944): [`sv.DetectionsSmoother`](/0.19.0/detection/tools/smoother/#supervision.detection.tools.smoother.DetectionsSmoother) removing `tracking_id` from `sv.Detections`.
+
 ### 0.18.0 <small>January 25, 2024</small>
 
-- Added [#633](https://github.com/roboflow/supervision/pull/720): [`sv.PercentageBarAnnotator`](0.18.0/annotators/#percentagebarannotator) allowing to annotate images and videos with percentage values representing confidence or other custom property.
+- Added [#720](https://github.com/roboflow/supervision/pull/720): [`sv.PercentageBarAnnotator`](/0.18.0/annotators/#percentagebarannotator) allowing to annotate images and videos with percentage values representing confidence or other custom property.
 
 ```python
 >>> import supervision as sv

docs/cookbooks.md

@@ -0,0 +1,7 @@
+---
+template: cookbooks.html
+comments: true
+hide:
+  - navigation
+  - toc
+---

docs/datasets/core.md

@@ -1,5 +1,6 @@
 ---
 comments: true
+status: new
 ---
 
 # Datasets

docs/datasets/utils.md

@@ -0,0 +1,18 @@
+---
+comments: true
+status: new
+---
+
+# Datasets Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.dataset.utils.rle_to_mask">rle_to_mask</a></h2>
+</div>
+
+:::supervision.dataset.utils.rle_to_mask
+
+<div class="md-typeset">
+  <h2><a href="#supervision.dataset.utils.mask_to_rle">mask_to_rle</a></h2>
+</div>
+
+:::supervision.dataset.utils.mask_to_rle

docs/deprecated.md

@@ -6,11 +6,14 @@ status: deprecated
 These features are phased out due to better alternatives or potential issues in future versions. Deprecated functionalities are supported for **three subsequent releases**, providing time for users to transition to updated methods.
 
 - [`Detections.from_froboflow`](detection/core.md/#supervision.detection.core.Detections.from_roboflow) is deprecated and will be removed in `supervision-0.22.0`. Use [`Detections.from_inference`](detection/core.md/#supervision.detection.core.Detections.from_inference) instead.
-- `Color.white()` is deprecated and will be removed in `supervision-0.22.0`. Use `Color.WHITE` instead.
-- `Color.black()` is deprecated and will be removed in `supervision-0.22.0`. Use `Color.BLACK` instead.
-- `Color.red()` is deprecated and will be removed in `supervision-0.22.0`. Use `Color.RED` instead.
-- `Color.green()` is deprecated and will be removed in `supervision-0.22.0`. Use `Color.GREEN` instead.
-- `Color.blue()` is deprecated and will be removed in `supervision-0.22.0`. Use `Color.BLUE` instead.
-- [`ColorPalette.default()`](draw/color.md/#supervision.draw.color.ColorPalette.default) is deprecated and will be removed in `supervision-0.22.0`. Use [`ColorPalette.DEFAULT`](draw/color.md/#supervision.draw.color.ColorPalette.DEFAULT) instead.
-- `BoxAnnotator` is deprecated and will be removed in `supervision-0.22.0`. Use [`BoundingBoxAnnotator`](annotators.md/#supervision.annotators.core.BoundingBoxAnnotator) and [`LabelAnnotator`](annotators.md/#supervision.annotators.core.LabelAnnotator) instead.
-- [`FPSMonitor.__call__`](utils/video.md/#supervision.utils.video.FPSMonitor.__call__) is deprecated and will be removed in `supervision-0.22.0`. Use [`FPSMonitor.fps`](utils/video.md/#supervision.utils.video.FPSMonitor.fps) instead.
+- The method `Color.white()` is deprecated and will be removed in `supervision-0.22.0`. Use the constant `Color.WHITE` instead.
+- The method `Color.black()` is deprecated and will be removed in `supervision-0.22.0`. Use the constant `Color.BLACK` instead.
+- The method `Color.red()` is deprecated and will be removed in `supervision-0.22.0`. Use the constant `Color.RED` instead.
+- The method `Color.green()` is deprecated and will be removed in `supervision-0.22.0`. Use the constant `Color.GREEN` instead.
+- The method `Color.blue()` is deprecated and will be removed in `supervision-0.22.0`. Use the constant `Color.BLUE` instead.
+- The method [`ColorPalette.default()`](draw/color.md/#supervision.draw.color.ColorPalette.default) is deprecated and will be removed in `supervision-0.22.0`. Use the constant [`ColorPalette.DEFAULT`](draw/color.md/#supervision.draw.color.ColorPalette.DEFAULT) instead.
+- `BoxAnnotator` is deprecated and will be removed in `supervision-0.22.0`. Use [`BoundingBoxAnnotator`](detection/annotators.md/#supervision.annotators.core.BoundingBoxAnnotator) and [`LabelAnnotator`](detection/annotators.md/#supervision.annotators.core.LabelAnnotator) instead.
+- The method [`FPSMonitor.__call__`](utils/video.md/#supervision.utils.video.FPSMonitor.__call__) is deprecated and will be removed in `supervision-0.22.0`. Use the attribute [`FPSMonitor.fps`](utils/video.md/#supervision.utils.video.FPSMonitor.fps) instead.
+- The `track_buffer`, `track_thresh`, and `match_thresh` parameters in [`ByterTrack`](trackers.md/#supervision.tracker.byte_tracker.core.ByteTrack) are deprecated and will be removed in `supervision-0.23.0`. Use `lost_track_buffer,` `track_activation_threshold`, and `minimum_matching_threshold` instead.
+- The `triggering_position ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) is deprecated and will be removed in `supervision-0.23.0`. Use `triggering_anchors ` instead.
+- The `frame_resolution_wh ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) is deprecated and will be removed in `supervision-0.24.0`.

docs/detection/annotators.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Annotators
@@ -260,15 +259,22 @@ status: new
 === "Label"
 
     ```python
-     import supervision as sv
+    import supervision as sv
 
     image = ...
     detections = sv.Detections(...)
 
+    labels = [
+        f"{class_name} {confidence:.2f}"
+        for class_name, confidence
+        in zip(detections['class_name'], detections.confidence)
+    ]
+
     label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
     annotated_frame = label_annotator.annotate(
         scene=image.copy(),
-        detections=detections
+        detections=detections,
+        labels=labels
     )
     ```
 
@@ -278,6 +284,52 @@ status: new
 
     </div>
 
+=== "RichLabel"
+
+    ```python
+    import supervision as sv
+
+    image = ...
+    detections = sv.Detections(...)
+
+    labels = [
+        f"{class_name} {confidence:.2f}"
+        for class_name, confidence
+        in zip(detections['class_name'], detections.confidence)
+    ]
+
+    rich_label_annotator = sv.RichLabelAnnotator(
+        font_path=".../font.ttf",
+        text_position=sv.Position.CENTER
+    )
+    annotated_frame = label_annotator.annotate(
+        scene=image.copy(),
+        detections=detections,
+        labels=labels
+    )
+    ```
+
+    <div class="result" markdown>
+
+    ![label-annotator-example](https://media.roboflow.com/supervision-annotator-examples/label-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Crop"
+
+    ```python
+    import supervision as sv
+
+    image = ...
+    detections = sv.Detections(...)
+
+    crop_annotator = sv.CropAnnotator()
+    annotated_frame = crop_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
+    ```
+
 === "Blur"
 
     ```python
@@ -470,6 +522,12 @@ status: new
 
 :::supervision.annotators.core.LabelAnnotator
 
+<div class="md-typeset">
+    <h2><a href="#supervision.annotators.core.RichLabelAnnotator">RichLabelAnnotator</a></h2>
+</div>
+
+:::supervision.annotators.core.RichLabelAnnotator
+
 <div class="md-typeset">
     <h2><a href="#supervision.annotators.core.BlurAnnotator">BlurAnnotator</a></h2>
 </div>
@@ -488,6 +546,12 @@ status: new
 
 :::supervision.annotators.core.TraceAnnotator
 
+<div class="md-typeset">
+    <h2><a href="#supervision.annotators.core.CropAnnotator">CropAnnotator</a></h2>
+</div>
+
+:::supervision.annotators.core.CropAnnotator
+
 <div class="md-typeset">
     <h2><a href="#supervision.annotators.core.ColorLookup">ColorLookup</a></h2>
 </div>

docs/detection/double_detection_filter.md

@@ -0,0 +1,30 @@
+---
+comments: true
+status: new
+---
+
+# Double Detection Filter
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.overlap_filter.OverlapFilter">OverlapFilter</a></h2>
+</div>
+
+:::supervision.detection.overlap_filter.OverlapFilter
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.overlap_filter.box_non_max_suppression">box_non_max_suppression</a></h2>
+</div>
+
+:::supervision.detection.overlap_filter.box_non_max_suppression
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.overlap_filter.mask_non_max_suppression">mask_non_max_suppression</a></h2>
+</div>
+
+:::supervision.detection.overlap_filter.mask_non_max_suppression
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.overlap_filter.box_non_max_merge">box_non_max_merge</a></h2>
+</div>
+
+:::supervision.detection.overlap_filter.box_non_max_merge

docs/detection/metrics.md

@@ -0,0 +1,17 @@
+---
+comments: true
+---
+
+# Metrics
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.detection.ConfusionMatrix">ConfusionMatrix</a></h2>
+</div>
+
+:::supervision.metrics.detection.ConfusionMatrix
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.detection.MeanAveragePrecision">MeanAveragePrecision</a></h2>
+</div>
+
+:::supervision.metrics.detection.MeanAveragePrecision

docs/detection/tools/inference_slicer.md

@@ -1,5 +1,6 @@
 ---
 comments: true
+status: new
 ---
 
 # InferenceSlicer

docs/detection/tools/line_zone.md

@@ -1,7 +1,16 @@
 ---
 comments: true
+status: new
 ---
 
-# LineZone
+<div class="md-typeset">
+  <h2>LineZone</h2>
+</div>
 
-:::supervision.detection.line_counter.LineZone
+:::supervision.detection.line_zone.LineZone
+
+<div class="md-typeset">
+  <h2>LineZoneAnnotator</h2>
+</div>
+
+:::supervision.detection.line_zone.LineZoneAnnotator

docs/detection/tools/polygon_zone.md

@@ -2,7 +2,9 @@
 comments: true
 ---
 
-# PolygonZone
+<div class="md-typeset">
+  <h2>PolygonZone</h2>
+</div>
 
 :::supervision.detection.tools.polygon_zone.PolygonZone
 

docs/detection/tools/save_detections.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Save Detections
@@ -10,3 +9,9 @@ status: new
 </div>
 
 :::supervision.detection.tools.csv_sink.CSVSink
+
+<div class="md-typeset">
+  <h2>JSON Sink</h2>
+</div>
+
+:::supervision.detection.tools.json_sink.JSONSink

docs/detection/tools/smoother.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Detection Smoother

docs/detection/utils.md

@@ -5,55 +5,85 @@ comments: true
 # Detection Utils
 
 <div class="md-typeset">
-  <h2>box_iou_batch</h2>
+  <h2><a href="#supervision.detection.utils.box_iou_batch">box_iou_batch</a></h2>
 </div>
 
 :::supervision.detection.utils.box_iou_batch
 
 <div class="md-typeset">
-  <h2>non_max_suppression</h2>
+  <h2><a href="#supervision.detection.utils.mask_iou_batch">mask_iou_batch</a></h2>
 </div>
 
-:::supervision.detection.utils.non_max_suppression
+:::supervision.detection.utils.mask_iou_batch
 
 <div class="md-typeset">
-    <h2>polygon_to_mask</h2>
+  <h2><a href="#supervision.detection.utils.polygon_to_mask">polygon_to_mask</a></h2>
 </div>
 
 :::supervision.detection.utils.polygon_to_mask
 
 <div class="md-typeset">
-    <h2>mask_to_xyxy</h2>
+  <h2><a href="#supervision.detection.utils.mask_to_xyxy">mask_to_xyxy</a></h2>
 </div>
 
 :::supervision.detection.utils.mask_to_xyxy
 
 <div class="md-typeset">
-    <h2>mask_to_polygons</h2>
+  <h2><a href="#supervision.detection.utils.mask_to_polygons">mask_to_polygons</a></h2>
 </div>
 
 :::supervision.detection.utils.mask_to_polygons
 
 <div class="md-typeset">
-    <h2>polygon_to_xyxy</h2>
+  <h2><a href="#supervision.detection.utils.polygon_to_xyxy">polygon_to_xyxy</a></h2>
 </div>
 
 :::supervision.detection.utils.polygon_to_xyxy
 
 <div class="md-typeset">
-    <h2>filter_polygons_by_area</h2>
+  <h2><a href="#supervision.detection.utils.filter_polygons_by_area">filter_polygons_by_area</a></h2>
 </div>
 
 :::supervision.detection.utils.filter_polygons_by_area
 
 <div class="md-typeset">
-    <h2>move_boxes</h2>
+  <h2><a href="#supervision.detection.utils.move_boxes">move_boxes</a></h2>
 </div>
 
 :::supervision.detection.utils.move_boxes
 
 <div class="md-typeset">
-    <h2>scale_boxes</h2>
+  <h2><a href="#supervision.detection.utils.move_masks">move_masks</a></h2>
+</div>
+
+:::supervision.detection.utils.move_masks
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.scale_boxes">scale_boxes</a></h2>
 </div>
 
 :::supervision.detection.utils.scale_boxes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.clip_boxes">clip_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.clip_boxes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.pad_boxes">pad_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.pad_boxes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.contains_holes">contains_holes</a></h2>
+</div>
+
+:::supervision.detection.utils.contains_holes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.contains_multiple_segments">contains_multiple_segments</a></h2>
+</div>
+
+:::supervision.detection.utils.contains_multiple_segments

docs/draw/color.md

@@ -1,13 +0,0 @@
----
-comments: true
----
-
-# Color
-
-:::supervision.draw.color.Color
-
-<div class="md-typeset">
-  <h2>ColorPalette</h2>
-</div>
-
-:::supervision.draw.color.ColorPalette

docs/draw/utils.md

@@ -1,53 +0,0 @@
----
-comments: true
----
-
-# Draw Utils
-
-<div class="md-typeset">
-  <h2>draw_line</h2>
-</div>
-
-:::supervision.draw.utils.draw_line
-
-<div class="md-typeset">
-  <h2>draw_rectangle</h2>
-</div>
-
-:::supervision.draw.utils.draw_rectangle
-
-<div class="md-typeset">
-  <h2>draw_filled_rectangle</h2>
-</div>
-
-:::supervision.draw.utils.draw_filled_rectangle
-
-<div class="md-typeset">
-  <h2>draw_polygon</h2>
-</div>
-
-:::supervision.draw.utils.draw_polygon
-
-<div class="md-typeset">
-  <h2>draw_text</h2>
-</div>
-
-:::supervision.draw.utils.draw_text
-
-<div class="md-typeset">
-  <h2>draw_image</h2>
-</div>
-
-:::supervision.draw.utils.draw_image
-
-<div class="md-typeset">
-  <h2>calculate_dynamic_font_scale</h2>
-</div>
-
-:::supervision.draw.utils.calculate_dynamic_text_scale
-
-<div class="md-typeset">
-  <h2>calculate_dynamic_line_thickness</h2>
-</div>
-
-:::supervision.draw.utils.calculate_dynamic_line_thickness

docs/geometry/core.md

@@ -1,7 +0,0 @@
----
-comments: true
----
-
-# Position
-
-:::supervision.geometry.core.Position

docs/how_to/detect_and_annotate.md

@@ -4,17 +4,31 @@ comments: true
 
 # Detect and Annotate
 
-Supervision offers a streamlined solution to effortlessly annotate predictions from a
-range of object detection and segmentation models. This guide demonstrates how to
-execute inference using the YOLOv8 model with either the
-[Inference](https://github.com/roboflow/inference) or
-[Ultralytics](https://github.com/ultralytics/ultralytics) packages. Following this,
-you'll learn how to import these predictions into Supervision for image annotation
-purposes.
+Supervision provides a seamless process for annotating predictions generated by various
+object detection and segmentation models. This guide shows how to perform inference
+with the  [Inference](https://github.com/roboflow/inference),
+[Ultralytics](https://github.com/ultralytics/ultralytics) or
+[Transformers](https://github.com/huggingface/transformers) packages. Following this,
+you'll learn how to import these predictions into Supervision and use them to annotate
+source image.
 
-## Run Inference
+![basic-annotation](https://media.roboflow.com/supervision_detect_and_annotate_example_1.png)
 
-First, you'll need to obtain predictions from your object detection or segmentation model.
+## Run Detection
+
+First, you'll need to obtain predictions from your object detection or segmentation
+model.
+
+=== "Inference"
+
+    ```python
+    import cv2
+    from inference import get_model
+
+    model = get_model(model_id="yolov8n-640")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+    results = model.infer(image)[0]
+    ```
 
 === "Ultralytics"
 
@@ -23,105 +37,115 @@ First, you'll need to obtain predictions from your object detection or segmentat
     from ultralytics import YOLO
 
     model = YOLO("yolov8n.pt")
-    image = cv2.imread(<PATH TO IMAGE>)
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
     results = model(image)[0]
     ```
 
-=== "Inference"
+=== "Transformers"
 
     ```python
-    import cv2
-    from inference.models.utils import get_roboflow_model
+    import torch
+    from PIL import Image
+    from transformers import DetrImageProcessor, DetrForObjectDetection
 
-    model = get_roboflow_model(model_id="yolov8n-640", api_key=<ROBOFLOW API KEY>)
-    image = cv2.imread(<PATH TO IMAGE>)
-    results = model.infer(image)[0]
+    processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
+    model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")
+
+    image = Image.open(<SOURCE_IMAGE_PATH>)
+    inputs = processor(images=image, return_tensors="pt")
+
+    with torch.no_grad():
+        outputs = model(**inputs)
+
+    width, height = image.size
+    target_size = torch.tensor([[height, width]])
+    results = processor.post_process_object_detection(
+        outputs=outputs, target_sizes=target_size)[0]
     ```
 
 ## Load Predictions into Supervision
 
 Now that we have predictions from a model, we can load them into Supervision.
 
-=== "Ultralytics"
-
-    We can do so using the [`sv.Detections.from_ultralytics`](/latest/detection/core/#supervision.detection.core.Detections.from_ultralytics) method, which accepts model results from both detection and segmentation models.
-
-    ```python
-    import cv2
-    import supervision as sv
-    from ultralytics import YOLO
-
-    model = YOLO("yolov8n.pt")
-    image = cv2.imread(<PATH TO IMAGE>)
-    results = model(image)[0]
-    detections = sv.Detections.from_ultralytics(results)
-    ```
-
 === "Inference"
 
-    We can do so using the [`sv.Detections.from_inference`](/latest/detection/core/#supervision.detection.core.Detections.from_inference) method, which accepts model results from both detection and segmentation models.
+    We can do so using the [`sv.Detections.from_inference`](detection/core/#supervision.detection.core.Detections.from_inference) method, which accepts model results from both detection and segmentation models.
 
-    ```python
+    ```{ .py hl_lines="2 8" }
     import cv2
     import supervision as sv
-    from inference.models.utils import get_roboflow_model
+    from inference import get_model
 
-    model = get_roboflow_model(model_id="yolov8n-640", api_key=<ROBOFLOW API KEY>
-    image = cv2.imread(<PATH TO IMAGE>)
+    model = get_model(model_id="yolov8n-640")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
     results = model.infer(image)[0]
     detections = sv.Detections.from_inference(results)
     ```
 
-You can conveniently load predictions from other computer vision frameworks and libraries using:
-
-- [`from_deepsparse`](/latest/detection/core/#supervision.detection.core.Detections.from_deepsparse) ([Deepsparse](https://github.com/neuralmagic/deepsparse))
-- [`from_detectron2`](/latest/detection/core/#supervision.detection.core.Detections.from_detectron2) ([Detectron2](https://github.com/facebookresearch/detectron2))
-- [`from_mmdetection`](/latest/detection/core/#supervision.detection.core.Detections.from_mmdetection) ([MMDetection](https://github.com/open-mmlab/mmdetection))
-- [`from_inference`](/latest/detection/core/#supervision.detection.core.Detections.from_inference) ([Roboflow Inference](https://github.com/roboflow/inference))
-- [`from_sam`](/latest/detection/core/#supervision.detection.core.Detections.from_sam) ([Segment Anything Model](https://github.com/facebookresearch/segment-anything))
-- [`from_transformers`](/latest/detection/core/#supervision.detection.core.Detections.from_transformers) ([HuggingFace Transformers](https://github.com/huggingface/transformers))
-- [`from_yolo_nas`](/latest/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`](/latest/annotators/#supervision.annotators.core.BoundingBoxAnnotator) and [`sv.LabelAnnotator`](/latest/annotators/#supervision.annotators.core.LabelAnnotator) classes. If you are running the segmentation model [`sv.MaskAnnotator`](/latest/annotators/#supervision.annotators.core.MaskAnnotator) is a drop-in replacement for [`sv.BoundingBoxAnnotator`](/latest/annotators/#supervision.annotators.core.BoundingBoxAnnotator) that will allow you to draw masks instead of boxes.
-
 === "Ultralytics"
 
-    ```python
+    We can do so using the [`sv.Detections.from_ultralytics`](detection/core/#supervision.detection.core.Detections.from_ultralytics) method, which accepts model results from both detection and segmentation models.
+
+    ```{ .py hl_lines="2 8" }
     import cv2
     import supervision as sv
     from ultralytics import YOLO
 
     model = YOLO("yolov8n.pt")
-    image = cv2.imread(<PATH TO IMAGE>)
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
     results = model(image)[0]
     detections = sv.Detections.from_ultralytics(results)
-
-    bounding_box_annotator = sv.BoundingBoxAnnotator()
-    label_annotator = sv.LabelAnnotator()
-
-    labels = [
-        model.model.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)
     ```
 
+=== "Transformers"
+
+    We can do so using the [`sv.Detections.from_transformers`](detection/core/#supervision.detection.core.Detections.from_transformers) method, which accepts model results from both detection and segmentation models.
+
+    ```{ .py hl_lines="2 19-21" }
+    import torch
+    import supervision as sv
+    from PIL import Image
+    from transformers import DetrImageProcessor, DetrForObjectDetection
+
+    processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
+    model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")
+
+    image = Image.open(<SOURCE_IMAGE_PATH>)
+    inputs = processor(images=image, return_tensors="pt")
+
+    with torch.no_grad():
+        outputs = model(**inputs)
+
+    width, height = image.size
+    target_size = torch.tensor([[height, width]])
+    results = processor.post_process_object_detection(
+        outputs=outputs, target_sizes=target_size)[0]
+    detections = sv.Detections.from_transformers(
+        transformers_results=results,
+        id2label=model.config.id2label)
+    ```
+
+You can load predictions from other computer vision frameworks and libraries using:
+
+- [`from_deepsparse`](/latest/detection/core/#supervision.detection.core.Detections.from_deepsparse) ([Deepsparse](https://github.com/neuralmagic/deepsparse))
+- [`from_detectron2`](/latest/detection/core/#supervision.detection.core.Detections.from_detectron2) ([Detectron2](https://github.com/facebookresearch/detectron2))
+- [`from_mmdetection`](/latest/detection/core/#supervision.detection.core.Detections.from_mmdetection) ([MMDetection](https://github.com/open-mmlab/mmdetection))
+- [`from_sam`](/latest/detection/core/#supervision.detection.core.Detections.from_sam) ([Segment Anything Model](https://github.com/facebookresearch/segment-anything))
+- [`from_yolo_nas`](/latest/detection/core/#supervision.detection.core.Detections.from_yolo_nas) ([YOLO-NAS](https://github.com/Deci-AI/super-gradients/blob/master/YOLONAS.md))
+
+## Annotate Image with Detections
+
+Finally, we can annotate the image with the predictions. Since we are working with an object detection model, we will use the [`sv.BoundingBoxAnnotator`](/latest/annotators/#supervision.annotators.core.BoundingBoxAnnotator) and [`sv.LabelAnnotator`](/latest/annotators/#supervision.annotators.core.LabelAnnotator) classes.
+
 === "Inference"
 
-    ```python
+    ```{ .py hl_lines="10-16" }
     import cv2
     import supervision as sv
-    from inference.models.utils import get_roboflow_model
+    from inference import get_model
 
-    model = get_roboflow_model(model_id="yolov8n-640", api_key=<ROBOFLOW API KEY>
-    image = cv2.imread(<PATH TO IMAGE>)
+    model = get_model(model_id="yolov8n-640")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
     results = model.infer(image)[0]
     detections = sv.Detections.from_inference(results)
 
@@ -134,12 +158,253 @@ Finally, we can annotate the image with the predictions. Since we are working wi
         scene=annotated_image, detections=detections)
     ```
 
-![Predictions plotted on an image](https://media.roboflow.com/supervision_annotate_example.png)
+=== "Ultralytics"
 
-## Display Annotated Image
+    ```{ .py hl_lines="10-16" }
+    import cv2
+    import supervision as sv
+    from ultralytics import YOLO
 
-To display the annotated image in Jupyter Notebook or Google Colab, use the [`sv.plot_image`](/latest/utils/notebook/#supervision.utils.notebook.plot_image) function.
+    model = YOLO("yolov8n.pt")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+    results = model(image)[0]
+    detections = sv.Detections.from_ultralytics(results)
 
-```python
-sv.plot_image(annotated_image)
-```
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    annotated_image = bounding_box_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+=== "Transformers"
+
+    ```{ .py hl_lines="23-30" }
+    import torch
+    import supervision as sv
+    from PIL import Image
+    from transformers import DetrImageProcessor, DetrForObjectDetection
+
+    processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
+    model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")
+
+    image = Image.open(<SOURCE_IMAGE_PATH>)
+    inputs = processor(images=image, return_tensors="pt")
+
+    with torch.no_grad():
+        outputs = model(**inputs)
+
+    width, height = image.size
+    target_size = torch.tensor([[height, width]])
+    results = processor.post_process_object_detection(
+        outputs=outputs, target_sizes=target_size)[0]
+    detections = sv.Detections.from_transformers(
+        transformers_results=results,
+        id2label=model.config.id2label)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    annotated_image = bounding_box_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+![basic-annotation](https://media.roboflow.com/supervision_detect_and_annotate_example_1.png)
+
+## Display Custom Labels
+
+By default, [`sv.LabelAnnotator`](/latest/annotators/#supervision.annotators.core.LabelAnnotator)
+will label each detection with its `class_name` (if possible) or `class_id`. You can
+override this behavior by passing a list of custom `labels` to the `annotate` method.
+
+=== "Inference"
+
+    ```{ .py hl_lines="13-17 22" }
+    import cv2
+    import supervision as sv
+    from inference import get_model
+
+    model = get_model(model_id="yolov8n-640")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+    results = model.infer(image)[0]
+    detections = sv.Detections.from_inference(results)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    labels = [
+        f"{class_name} {confidence:.2f}"
+        for class_name, confidence
+        in zip(detections['class_name'], detections.confidence)
+    ]
+
+    annotated_image = bounding_box_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections, labels=labels)
+    ```
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="13-17 22" }
+    import cv2
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8n.pt")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+    results = model(image)[0]
+    detections = sv.Detections.from_ultralytics(results)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    labels = [
+        f"{class_name} {confidence:.2f}"
+        for class_name, confidence
+        in zip(detections['class_name'], detections.confidence)
+    ]
+
+    annotated_image = bounding_box_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections, labels=labels)
+    ```
+
+=== "Transformers"
+
+    ```{ .py hl_lines="26-30 35" }
+    import torch
+    import supervision as sv
+    from PIL import Image
+    from transformers import DetrImageProcessor, DetrForObjectDetection
+
+    processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
+    model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")
+
+    image = Image.open(<SOURCE_IMAGE_PATH>)
+    inputs = processor(images=image, return_tensors="pt")
+
+    with torch.no_grad():
+        outputs = model(**inputs)
+
+    width, height = image.size
+    target_size = torch.tensor([[height, width]])
+    results = processor.post_process_object_detection(
+        outputs=outputs, target_sizes=target_size)[0]
+    detections = sv.Detections.from_transformers(
+        transformers_results=results,
+        id2label=model.config.id2label)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    labels = [
+        f"{class_name} {confidence:.2f}"
+        for class_name, confidence
+        in zip(detections['class_name'], detections.confidence)
+    ]
+
+    annotated_image = bounding_box_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections, labels=labels)
+    ```
+
+![custom-label-annotation](https://media.roboflow.com/supervision_detect_and_annotate_example_2.png)
+
+## Annotate Image with Segmentations
+
+If you are running the segmentation model
+[`sv.MaskAnnotator`](/latest/annotators/#supervision.annotators.core.MaskAnnotator)
+is a drop-in replacement for
+[`sv.BoundingBoxAnnotator`](/latest/annotators/#supervision.annotators.core.BoundingBoxAnnotator)
+that will allow you to draw masks instead of boxes.
+
+=== "Inference"
+
+    ```python
+    import cv2
+    import supervision as sv
+    from inference import get_model
+
+    model = get_model(model_id="yolov8n-seg-640")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+    results = model.infer(image)[0]
+    detections = sv.Detections.from_inference(results)
+
+    mask_annotator = sv.MaskAnnotator()
+    label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER_OF_MASS)
+
+    annotated_image = mask_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+=== "Ultralytics"
+
+    ```python
+    import cv2
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8n-seg.pt")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+    results = model(image)[0]
+    detections = sv.Detections.from_ultralytics(results)
+
+    mask_annotator = sv.MaskAnnotator()
+    label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER_OF_MASS)
+
+    annotated_image = mask_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+=== "Transformers"
+
+    ```python
+    import torch
+    import supervision as sv
+    from PIL import Image
+    from transformers import DetrImageProcessor, DetrForSegmentation
+
+    processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50-panoptic")
+    model = DetrForSegmentation.from_pretrained("facebook/detr-resnet-50-panoptic")
+
+    image = Image.open(<SOURCE_IMAGE_PATH>)
+    inputs = processor(images=image, return_tensors="pt")
+
+    with torch.no_grad():
+        outputs = model(**inputs)
+
+    width, height = image.size
+    target_size = torch.tensor([[height, width]])
+    results = processor.post_process_segmentation(
+        outputs=outputs, target_sizes=target_size)[0]
+    detections = sv.Detections.from_transformers(
+        transformers_results=results,
+        id2label=model.config.id2label)
+
+    mask_annotator = sv.MaskAnnotator()
+    label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER_OF_MASS)
+
+    labels = [
+        f"{class_name} {confidence:.2f}"
+        for class_name, confidence
+        in zip(detections['class_name'], detections.confidence)
+    ]
+
+    annotated_image = mask_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections, labels=labels)
+    ```
+
+![segmentation-annotation](https://media.roboflow.com/supervision_detect_and_annotate_example_3.png)

docs/how_to/detect_small_objects.md

@@ -0,0 +1,326 @@
+---
+comments: true
+status: new
+---
+
+# Detect Small Objects
+
+This guide shows how to detect small objects
+with the [Inference](https://github.com/roboflow/inference),
+[Ultralytics](https://github.com/ultralytics/ultralytics) or
+[Transformers](https://github.com/huggingface/transformers) packages using
+[`InferenceSlicer`](/latest/detection/tools/inference_slicer/#supervision.detection.tools.inference_slicer.InferenceSlicer).
+
+<video controls>
+    <source src="https://media.roboflow.com/supervision_detect_small_objects_example.mp4" type="video/mp4">
+</video>
+
+## Baseline Detection
+
+Small object detection in high-resolution images presents challenges due to the objects'
+size relative to the image resolution.
+
+=== "Inference"
+
+    ```python
+    import cv2
+    import supervision as sv
+    from inference import get_model
+
+    model = get_model(model_id="yolov8x-640")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+    results = model.infer(image)[0]
+    detections = sv.Detections.from_inference(results)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    annotated_image = bounding_box_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+=== "Ultralytics"
+
+    ```python
+    import cv2
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8x.pt")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+    results = model(image)[0]
+    detections = sv.Detections.from_ultralytics(results)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    annotated_image = bounding_box_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+=== "Transformers"
+
+    ```python
+    import torch
+    import supervision as sv
+    from PIL import Image
+    from transformers import DetrImageProcessor, DetrForSegmentation
+
+    processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
+    model = DetrForSegmentation.from_pretrained("facebook/detr-resnet-50")
+
+    image = Image.open(<SOURCE_IMAGE_PATH>)
+    inputs = processor(images=image, return_tensors="pt")
+
+    with torch.no_grad():
+        outputs = model(**inputs)
+
+    width, height = image_slice.size
+    target_size = torch.tensor([[width, height]])
+    results = processor.post_process_object_detection(
+        outputs=outputs, target_sizes=target_size)[0]
+    detections = sv.Detections.from_transformers(results)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    labels = [
+        model.config.id2label[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)
+    ```
+
+![basic-detection](https://media.roboflow.com/supervision_detect_small_objects_example_1.png)
+
+## Input Resolution
+
+Modifying the input resolution of images before detection can enhance small object
+identification at the cost of processing speed and increased memory usage. This method
+is less effective for ultra-high-resolution images (4K and above).
+
+=== "Inference"
+
+    ```{ .py hl_lines="5" }
+    import cv2
+    import supervision as sv
+    from inference import get_model
+
+    model = get_model(model_id="yolov8x-1280")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+    results = model.infer(image)[0]
+    detections = sv.Detections.from_inference(results)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    annotated_image = bounding_box_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="7" }
+    import cv2
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8x.pt")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+    results = model(image, imgsz=1280)[0]
+    detections = sv.Detections.from_ultralytics(results)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    annotated_image = bounding_box_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+![detection-with-high-input-resolution](https://media.roboflow.com/supervision_detect_small_objects_example_2.png)
+
+## Inference Slicer
+
+[`InferenceSlicer`](/latest/detection/tools/inference_slicer/#supervision.detection.tools.inference_slicer.InferenceSlicer)
+processes high-resolution images by dividing them into smaller segments, detecting
+objects within each, and aggregating the results.
+
+<video controls>
+    <source src="https://media.roboflow.com/supervision_detect_small_objects_example_2.mp4" type="video/mp4">
+</video>
+
+=== "Inference"
+
+    ```{ .py hl_lines="9-14" }
+    import cv2
+    import numpy as np
+    import supervision as sv
+    from inference import get_model
+
+    model = get_model(model_id="yolov8x-640")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+
+    def callback(image_slice: np.ndarray) -> sv.Detections:
+        results = model.infer(image_slice)[0]
+        return sv.Detections.from_inference(results)
+
+    slicer = sv.InferenceSlicer(callback = callback)
+    detections = slicer(image)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    annotated_image = bounding_box_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="9-14" }
+    import cv2
+    import numpy as np
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8x.pt")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+
+    def callback(image_slice: np.ndarray) -> sv.Detections:
+        result = model(image_slice)[0]
+        return sv.Detections.from_ultralytics(result)
+
+    slicer = sv.InferenceSlicer(callback = callback)
+    detections = slicer(image)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    annotated_image = bounding_box_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+=== "Transformers"
+
+    ```{ .py hl_lines="13-28" }
+    import cv2
+    import torch
+    import numpy as np
+    import supervision as sv
+    from PIL import Image
+    from transformers import DetrImageProcessor, DetrForObjectDetection
+
+    processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
+    model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")
+
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+
+    def callback(image_slice: np.ndarray) -> sv.Detections:
+        image_slice = cv2.cvtColor(image_slice, cv2.COLOR_BGR2RGB)
+        image_slice = Image.fromarray(image_slice)
+        inputs = processor(images=image_slice, return_tensors="pt")
+
+        with torch.no_grad():
+            outputs = model(**inputs)
+
+        width, height = image_slice.size
+        target_size = torch.tensor([[width, height]])
+        results = processor.post_process_object_detection(
+            outputs=outputs, target_sizes=target_size)[0]
+        return sv.Detections.from_transformers(results)
+
+    slicer = sv.InferenceSlicer(callback = callback)
+    detections = slicer(image)
+
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    labels = [
+        model.config.id2label[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)
+    ```
+
+![detection-with-inference-slicer](https://media.roboflow.com/supervision_detect_small_objects_example_3.png)
+
+## Small Object Segmentation
+
+[`InferenceSlicer`](/latest/detection/tools/inference_slicer/#supervision.detection.tools.inference_slicer.InferenceSlicer) can perform segmentation tasks too.
+
+=== "Inference"
+
+    ```{ .py hl_lines="6 16 19-20" }
+    import cv2
+    import numpy as np
+    import supervision as sv
+    from inference import get_model
+
+    model = get_model(model_id="yolov8x-seg-640")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+
+    def callback(image_slice: np.ndarray) -> sv.Detections:
+        results = model.infer(image_slice)[0]
+        return sv.Detections.from_inference(results)
+
+    slicer = sv.InferenceSlicer(callback = callback)
+    detections = slicer(image)
+
+    mask_annotator = sv.MaskAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    annotated_image = mask_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="6 16 19-20" }
+    import cv2
+    import numpy as np
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8x-seg.pt")
+    image = cv2.imread(<SOURCE_IMAGE_PATH>)
+
+    def callback(image_slice: np.ndarray) -> sv.Detections:
+        result = model(image_slice)[0]
+        return sv.Detections.from_ultralytics(result)
+
+    slicer = sv.InferenceSlicer(callback = callback)
+    detections = slicer(image)
+
+    mask_annotator = sv.MaskAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    annotated_image = mask_annotator.annotate(
+        scene=image, detections=detections)
+    annotated_image = label_annotator.annotate(
+        scene=annotated_image, detections=detections)
+    ```
+
+![detection-with-inference-slicer](https://media.roboflow.com/supervision-docs/inference-slicer-segmentation-example.png)

docs/how_to/save_detections.md

@@ -0,0 +1,298 @@
+---
+comments: true
+---
+
+# Save Detections
+
+Supervision enables an easy way to save detections in .CSV and .JSON files for offline
+processing. This guide demonstrates how to perform video inference using the
+[Inference](https://github.com/roboflow/inference),
+[Ultralytics](https://github.com/ultralytics/ultralytics) or
+[Transformers](https://github.com/huggingface/transformers) packages and save their results with
+[`sv.CSVSink`](/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink) and
+[`sv.JSONSink`](/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.JSONSink).
+
+## Run Detection
+
+First, you'll need to obtain predictions from your object detection or segmentation
+model. You can learn more on this topic in our
+[How to Detect and Annotate](/latest/how_to/detect_and_annotate.md) guide.
+
+=== "Inference"
+
+    ```python
+    import supervision as sv
+    from inference import get_model
+
+    model = get_model(model_id="yolov8n-640")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    for frame in frames_generator:
+
+        results = model.infer(image)[0]
+        detections = sv.Detections.from_inference(results)
+    ```
+
+=== "Ultralytics"
+
+    ```python
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8n.pt")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    for frame in frames_generator:
+
+        results = model(frame)[0]
+        detections = sv.Detections.from_ultralytics(results)
+    ```
+
+=== "Transformers"
+
+    ```python
+    import torch
+    import supervision as sv
+    from transformers import DetrImageProcessor, DetrForObjectDetection
+
+    processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
+    model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    for frame in frames_generator:
+
+        frame = sv.cv2_to_pillow(frame)
+        inputs = processor(images=frame, return_tensors="pt")
+
+        with torch.no_grad():
+            outputs = model(**inputs)
+
+        width, height = frame.size
+        target_size = torch.tensor([[height, width]])
+        results = processor.post_process_object_detection(
+            outputs=outputs, target_sizes=target_size)[0]
+        detections = sv.Detections.from_transformers(results)
+    ```
+
+## Save Detections as CSV
+
+To save detections to a `.CSV` file, open our
+[`sv.CSVSink`](/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink)
+and then pass the
+[`sv.Detections`](/latest/detection/core/#supervision.detection.core.Detections)
+object resulting from the inference to it. Its fields are parsed and saved on disk.
+
+=== "Inference"
+
+    ```{ .py hl_lines="7 12" }
+    import supervision as sv
+    from inference import get_model
+
+    model = get_model(model_id="yolov8n-640")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    with sv.CSVSink(<TARGET_CSV_PATH>) as sink:
+        for frame in frames_generator:
+
+            results = model.infer(image)[0]
+            detections = sv.Detections.from_inference(results)
+            sink.append(detections, {})
+    ```
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="7 12" }
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8n.pt")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    with sv.CSVSink(<TARGET_CSV_PATH>) as sink:
+        for frame in frames_generator:
+
+            results = model(frame)[0]
+            detections = sv.Detections.from_ultralytics(results)
+            sink.append(detections, {})
+    ```
+
+=== "Transformers"
+
+    ```{ .py hl_lines="9 23" }
+    import torch
+    import supervision as sv
+    from transformers import DetrImageProcessor, DetrForObjectDetection
+
+    processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
+    model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    with sv.CSVSink(<TARGET_CSV_PATH>) as sink:
+        for frame in frames_generator:
+
+            frame = sv.cv2_to_pillow(frame)
+            inputs = processor(images=frame, return_tensors="pt")
+
+            with torch.no_grad():
+                outputs = model(**inputs)
+
+            width, height = frame.size
+            target_size = torch.tensor([[height, width]])
+            results = processor.post_process_object_detection(
+                outputs=outputs, target_sizes=target_size)[0]
+            detections = sv.Detections.from_transformers(results)
+            sink.append(detections, {})
+    ```
+
+| x_min   | y_min    | x_max   | y_max    | class_id | confidence | tracker_id | class_name |
+|---------|----------|---------|----------|----------|------------|------------|------------|
+| 2941.14 | 1269.31  | 3220.77 | 1500.67  | 2        | 0.8517     |            | car        |
+| 944.889 | 899.641  | 1235.42 | 1308.80  | 7        | 0.6752     |            | truck      |
+| 1439.78 | 1077.79  | 1621.27 | 1231.40  | 2        | 0.6450     |            | car        |
+
+## Custom Fields
+
+Besides regular fields in
+[`sv.Detections`](/latest/detection/core/#supervision.detection.core.Detections),
+[`sv.CSVSink`](/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink)
+also allows you to add custom information to each row, which can be passed via the
+`custom_data` dictionary. Let's utilize this feature to save information about the
+frame index from which the detections originate.
+
+=== "Inference"
+
+    ```{ .py hl_lines="8 12" }
+    import supervision as sv
+    from inference import get_model
+
+    model = get_model(model_id="yolov8n-640")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    with sv.CSVSink(<TARGET_CSV_PATH>) as sink:
+        for frame_index, frame in enumerate(frames_generator):
+
+            results = model.infer(image)[0]
+            detections = sv.Detections.from_inference(results)
+            sink.append(detections, {"frame_index": frame_index})
+    ```
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="8 12" }
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8n.pt")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    with sv.CSVSink(<TARGET_CSV_PATH>) as sink:
+        for frame_index, frame in enumerate(frames_generator):
+
+            results = model(frame)[0]
+            detections = sv.Detections.from_ultralytics(results)
+            sink.append(detections, {"frame_index": frame_index})
+    ```
+
+=== "Transformers"
+
+    ```{ .py hl_lines="10 23" }
+    import torch
+    import supervision as sv
+    from transformers import DetrImageProcessor, DetrForObjectDetection
+
+    processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
+    model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    with sv.CSVSink(<TARGET_CSV_PATH>) as sink:
+        for frame_index, frame in enumerate(frames_generator):
+
+            frame = sv.cv2_to_pillow(frame)
+            inputs = processor(images=frame, return_tensors="pt")
+
+            with torch.no_grad():
+                outputs = model(**inputs)
+
+            width, height = frame.size
+            target_size = torch.tensor([[height, width]])
+            results = processor.post_process_object_detection(
+                outputs=outputs, target_sizes=target_size)[0]
+            detections = sv.Detections.from_transformers(results)
+            sink.append(detections, {"frame_index": frame_index})
+    ```
+
+| x_min   | y_min    | x_max   | y_max    | class_id | confidence | tracker_id | class_name | frame_index |
+|---------|----------|---------|----------|----------|------------|------------|------------|-------------|
+| 2941.14 | 1269.31  | 3220.77 | 1500.67  | 2        | 0.8517     |            | car        | 0           |
+| 944.889 | 899.641  | 1235.42 | 1308.80  | 7        | 0.6752     |            | truck      | 0           |
+| 1439.78 | 1077.79  | 1621.27 | 1231.40  | 2        | 0.6450     |            | car        | 0           |
+
+## Save Detections as JSON
+
+If you prefer to save the result in a `.JSON` file instead of a `.CSV` file, all you
+need to do is replace
+[`sv.CSVSink`](/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink)
+with
+[`sv.JSONSink`](/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.JSONSink).
+
+=== "Inference"
+
+    ```{ .py hl_lines="7" }
+    import supervision as sv
+    from inference import get_model
+
+    model = get_model(model_id="yolov8n-640")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    with sv.JSONSink(<TARGET_CSV_PATH>) as sink:
+        for frame_index, frame in enumerate(frames_generator):
+
+            results = model.infer(image)[0]
+            detections = sv.Detections.from_inference(results)
+            sink.append(detections, {"frame_index": frame_index})
+    ```
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="7" }
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8n.pt")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    with sv.JSONSink(<TARGET_CSV_PATH>) as sink:
+        for frame_index, frame in enumerate(frames_generator):
+
+            results = model(frame)[0]
+            detections = sv.Detections.from_ultralytics(results)
+            sink.append(detections, {"frame_index": frame_index})
+    ```
+
+=== "Transformers"
+
+    ```{ .py hl_lines="9" }
+    import torch
+    import supervision as sv
+    from transformers import DetrImageProcessor, DetrForObjectDetection
+
+    processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
+    model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")
+    frames_generator = sv.get_video_frames_generator(<SOURCE_VIDEO_PATH>)
+
+    with sv.JSONSink(<TARGET_CSV_PATH>) as sink:
+        for frame_index, frame in enumerate(frames_generator):
+
+            frame = sv.cv2_to_pillow(frame)
+            inputs = processor(images=frame, return_tensors="pt")
+
+            with torch.no_grad():
+                outputs = model(**inputs)
+
+            width, height = frame.size
+            target_size = torch.tensor([[height, width]])
+            results = processor.post_process_object_detection(
+                outputs=outputs, target_sizes=target_size)[0]
+            detections = sv.Detections.from_transformers(results)
+            sink.append(detections, {"frame_index": frame_index})
+    ```

docs/index.md

@@ -1,16 +1,20 @@
 ---
+template: index.html
 comments: true
+hide:
+  - navigation
+  - toc
 ---
 
-<div align="center">
-  <p>
-    <a align="center" href="" target="_blank">
-      <img
-        width="850"
-        src="https://media.roboflow.com/open-source/supervision/rf-supervision-banner.png?updatedAt=1678995927529"
-      >
-    </a>
-  </p>
+<div class="md-typeset">
+  <h1></h1>
+</div>
+
+<div align="center" id="logo">
+  <a align="center" href="" target="_blank">
+      <img width="850"
+          src="https://media.roboflow.com/open-source/supervision/rf-supervision-banner.png?updatedAt=1678995927529">
+  </a>
 </div>
 
 ## 👋 Hello
@@ -26,7 +30,7 @@ We write your reusable computer vision tools. Whether you need to load your data
 
 ## 💻 Install
 
-You can install `supervision` with pip in a
+You can install `supervision` in a
 [**Python>=3.8**](https://www.python.org/) environment.
 
 !!! example "pip install (recommended)"
@@ -42,7 +46,25 @@ You can install `supervision` with pip in a
         If you require the full version of `supervision` with GUI support you can install the desktop version. This version includes the GUI components of OpenCV, allowing you to display images and videos on the screen.
 
         ```bash
-        pip install supervision[desktop]
+        pip install "supervision[desktop]"
+        ```
+
+!!! example "conda/mamba install"
+
+    === "conda"
+
+        [![conda-recipe](https://img.shields.io/badge/recipe-supervision-green.svg)](https://anaconda.org/conda-forge/supervision) [![conda-downloads](https://img.shields.io/conda/dn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision) [![conda-version](https://img.shields.io/conda/vn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision) [![conda-platforms](https://img.shields.io/conda/pn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision)
+
+        ```bash
+        conda install -c conda-forge supervision
+        ```
+
+    === "mamba"
+
+        [![mamba-recipe](https://img.shields.io/badge/recipe-supervision-green.svg)](https://anaconda.org/conda-forge/supervision) [![mamba-downloads](https://img.shields.io/conda/dn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision) [![mamba-version](https://img.shields.io/conda/vn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision) [![mamba-platforms](https://img.shields.io/conda/pn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision)
+
+        ```bash
+        mamba install -c conda-forge supervision
         ```
 
 !!! example "git clone (for development)"
@@ -84,7 +106,6 @@ You can install `supervision` with pip in a
         poetry install --extras "desktop"
         ```
 
-
 ## 🚀 Quickstart
 
 <div class="grid cards" markdown>
@@ -105,6 +126,14 @@ You can install `supervision` with pip in a
 
     [:octicons-arrow-right-24: Tutorial](how_to/track_objects.md)
 
+-   __Detect Small Objects__
+
+    ---
+
+    Learn how to detect small objects in images
+
+    [:octicons-arrow-right-24: Tutorial](how_to/detect_small_objects.md)
+
 -   > __Count Objects Crossing Line__
 
     ---

docs/javascripts/cookbooks-card.js

@@ -0,0 +1,142 @@
+document.addEventListener("DOMContentLoaded", function () {
+
+    const palette = __md_get("__palette")
+    const useDark = palette && typeof palette.color === "object" && palette.color.scheme === "slate"
+    const theme = useDark ? "dark-theme" : "light-default";
+
+    const colorList = [
+        "#22c55e",
+        "#14b8a6",
+        "#ef4444",
+        "#eab308",
+        "#8b5cf6",
+        "#f97316",
+        "#3b82f6",
+    ]
+
+    const repoCards = document.querySelectorAll(".repo-card");
+    const labelsAll = Array
+        .from(repoCards)
+        .flatMap((element) => element.getAttribute('data-labels').split(','))
+        .map(label => label.trim())
+        .filter(label => label !== '');
+    const uniqueLabels = [...new Set(labelsAll)];
+
+    const labelToColor = uniqueLabels.reduce((map, label, index) => {
+        map[label] = colorList[index % colorList.length];
+        return map;
+    }, {});
+
+
+  async function renderCard(element, elementIndex) {
+    const url = element.getAttribute('data-url');
+    const name = element.getAttribute('data-name');
+    const labels = element.getAttribute('data-labels');
+    const version = element.getAttribute('data-version');
+    const authors = element.getAttribute('data-author');
+
+    const labelHTML = labels ? labels.split(',').filter(label => label !== '').map((label, index) => {
+        const color = labelToColor[label.trim()];
+        return `
+            <span
+                class="label non-selectable-text"
+                style="background-color: ${color}"
+            >
+                ${label.trim()}
+            </span>
+        `;
+    }).join(' ') : '';
+
+    const authorArray = authors.split(',');
+    const authorDataArray = await Promise.all(authorArray.map(async (author) => {
+      const response = await fetch(`https://api.github.com/users/${author.trim()}`);
+      return await response.json();
+    }));
+
+    let authorAvatarsHTML = authorDataArray.map((authorData, index) => {
+        const marginLeft = index === 0 ? '0' : '-10px';
+        const zIndex = 4 - index;
+        return `
+            <div
+                class="author-container"
+                data-login="${authorData.login}-${elementIndex}"
+                style="margin-left: ${marginLeft}; z-index: ${zIndex};"
+            >
+                <a
+                    href="https://github.com/${authorData.login}"
+                    target="_blank"
+                    style="line-height: 0;"
+                >
+                    <img
+                        class="author-avatar"
+                        src="${authorData.avatar_url}"
+                        alt="${authorData.login}'s avatar"
+                    >
+                </a>
+            </div>
+        `;
+    }).join('');
+
+    let authorNamesHTML = authorDataArray.map(
+        authorData => `
+            <span
+                class="author-name"
+                data-login="${authorData.login}-${elementIndex}"
+                style="color: ${theme.color}"
+            >
+            <a href="https://github.com/${authorData.login}" target="_blank">
+                ${authorData.login}
+            </a>
+        </span>`
+    ).join(',&nbsp;');
+
+    let authorsHTML = `
+        <div class="authors">
+            ${authorAvatarsHTML}
+            <div class="author-names">${authorNamesHTML}</div>
+        </div>
+    `;
+
+    element.innerText = `
+      <a style="text-decoration: none; color: inherit;" href="${url}">
+        <div style="flex-direction: column; height: 100%; display: flex;
+        font-family: -apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif,Apple Color Emoji,Segoe UI Emoji; background: ${theme.background}; font-size: 14px; line-height: 1.5; color: ${theme.color}">
+          <div style="display: flex; align-items: center;">
+            <span style="font-weight: 700; font-size: 1rem; color: ${theme.linkColor};">
+              ${name}
+            </span>
+          </div>
+          ${authorsHTML}
+          <div style="font-size: 12px; color: ${theme.color}; display: flex; flex: 0; justify-content: space-between">
+            <div style="display: flex; align-items: center;">
+              <img src="/assets/supervision-lenny.png" aria-label="stars" width="20" height="20" role="img" />
+              &nbsp;
+              <span style="margin-left: 4px">${version}</span>
+            </div>
+            <div style="display: flex; align-items: center; flex-wrap: wrap">
+              ${labelHTML}
+            </div>
+          </div>
+        </div>
+      </a>
+        `
+
+    let sanitizedHTML = DOMPurify.sanitize(element.innerText);
+    element.innerHTML = sanitizedHTML;
+
+    document.querySelectorAll('.author-name').forEach(element => {
+        element.addEventListener('mouseenter', function() {
+            const login = this.getAttribute('data-login');
+            document.querySelector(`.author-container[data-login="${login}"]`).classList.add('hover');
+        });
+
+        element.addEventListener('mouseleave', function() {
+            const login = this.getAttribute('data-login');
+            document.querySelector(`.author-container[data-login="${login}"]`).classList.remove('hover');
+        });
+    });
+  }
+    repoCards.forEach((element, index) => {
+        renderCard(element, index);
+    });
+})

docs/keypoint/annotators.md

@@ -0,0 +1,97 @@
+---
+comments: true
+status: new
+---
+
+# Annotators
+
+=== "VertexAnnotator"
+
+    ```python
+    import supervision as sv
+
+    image = ...
+    key_points = sv.KeyPoints(...)
+
+    vertex_annotator = sv.VertexAnnotator(
+        color=sv.Color.GREEN,
+        radius=10
+    )
+    annotated_frame = vertex_annotator.annotate(
+        scene=image.copy(),
+        key_points=key_points
+    )
+    ```
+
+    <div class="result" markdown>
+
+    ![vertex-annotator-example](https://media.roboflow.com/supervision-annotator-examples/vertex-annotator-example.png){ align=center width="800" }
+
+    </div>
+
+=== "EdgeAnnotator"
+
+    ```python
+    import supervision as sv
+
+    image = ...
+    key_points = sv.KeyPoints(...)
+
+    edge_annotator = sv.EdgeAnnotator(
+        color=sv.Color.GREEN,
+        thickness=5
+    )
+    annotated_frame = edge_annotator.annotate(
+        scene=image.copy(),
+        key_points=key_points
+    )
+    ```
+
+    <div class="result" markdown>
+
+    ![edge-annotator-example](https://media.roboflow.com/supervision-annotator-examples/edge-annotator-example.png){ align=center width="800" }
+
+    </div>
+
+=== "VertexLabelAnnotator"
+
+    ```python
+    import supervision as sv
+
+    image = ...
+    key_points = sv.KeyPoints(...)
+
+    vertex_label_annotator = sv.VertexLabelAnnotator(
+        color=sv.Color.GREEN,
+        text_color=sv.Color.BLACK,
+        border_radius=5
+    )
+    annotated_frame = vertex_label_annotator.annotate(
+        scene=image.copy(),
+        key_points=key_points
+    )
+    ```
+
+    <div class="result" markdown>
+
+    ![vertex-label-annotator-example](https://media.roboflow.com/supervision-annotator-examples/vertex-label-annotator-example.png){ align=center width="800" }
+
+    </div>
+
+<div class="md-typeset">
+  <h2><a href="#supervision.keypoint.annotators.VertexAnnotator">VertexAnnotator</a></h2>
+</div>
+
+:::supervision.keypoint.annotators.VertexAnnotator
+
+<div class="md-typeset">
+  <h2><a href="#supervision.keypoint.annotators.EdgeAnnotator">EdgeAnnotator</a></h2>
+</div>
+
+:::supervision.keypoint.annotators.EdgeAnnotator
+
+<div class="md-typeset">
+  <h2><a href="#supervision.keypoint.annotators.VertexLabelAnnotator">VertexLabelAnnotator</a></h2>
+</div>
+
+:::supervision.keypoint.annotators.VertexLabelAnnotator

docs/keypoint/core.md

@@ -0,0 +1,8 @@
+---
+comments: true
+status: new
+---
+
+# Keypoint Detection
+
+:::supervision.keypoint.core.KeyPoints

docs/metrics/detection.md

@@ -1,22 +0,0 @@
----
-comments: true
----
-
-#  Detection Metrics
-
-!!! warning
-
-    Evaluation API is still fluid and may change. If you use Evaluation API in your project until further notice, freeze the
-    `supervision` version in your `requirements.txt` or `setup.py`.
-
-<div class="md-typeset">
-    <h2><a href="#supervision.metrics.detection.ConfusionMatrix">ConfusionMatrix</a></h2>
-</div>
-
-:::supervision.metrics.detection.ConfusionMatrix
-
-<div class="md-typeset">
-    <h2><a href="#supervision.annotators.core.MeanAveragePrecision">MeanAveragePrecision</a></h2>
-</div>
-
-:::supervision.metrics.detection.MeanAveragePrecision

docs/notebooks/download-supervision-assets.ipynb

@@ -0,0 +1,102 @@
+{
+    "cells": [
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "# Download Supervision Assets\n",
+                "\n",
+                "---\n",
+                "\n",
+                "[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow/supervision/blob/develop/docs/notebooks/download-supervision-assets.ipynb)\n",
+                "\n",
+                "When experimenting with interesting and useful features of the Supervision package, it's important to have some sort of image or video data to experiment with. Luckily for us, Supervision ships with [Assets](https://supervision.roboflow.com/latest/assets/)! Assets is a collection of videos that you can utilize to start experimenting with the various features Supervision has to offer. Let's take a look at how to use this resource.\n",
+                "\n",
+                "## Install Dependencies"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 10,
+            "metadata": {
+                "vscode": {
+                    "languageId": "shellscript"
+                }
+            },
+            "outputs": [],
+            "source": [
+                "!pip install -q \"supervision[assets]\""
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "## Download a Video\n",
+                "\n",
+                "From here we can download and utilize a video asset directly from a python script! Note below that we're utilizing the method `download_assets` to download the `VideoAssets.SUBWAY` video to our local directory. This method returns the file path, so we can then utilize this path for additional experimentation. From here, you will see a video asset to experiment with in your local directory. "
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "from supervision.assets import download_assets, VideoAssets\n",
+                "\n",
+                "# Download the a video of the subway.\n",
+                "path_to_video = download_assets(VideoAssets.SUBWAY)"
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "With this, we now have a high quality video asset for use in demos. Let's take a look at what we downloaded. Keep in mind that the video preview below works only in the web version of the cookbooks and not in Google Colab.\n"
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "<div style=\"display: flex; justify-content: center;\">\n",
+                "    <video controls width=\"320\" height=\"240\">\n",
+                "        <source\n",
+                "            src=\"https://media.roboflow.com/supervision/video-examples/subway.mp4\"\n",
+                "            type=\"video/mp4\"\n",
+                "        >\n",
+                "    </video>\n",
+                "</div>"
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "We're now equipt with a video asset from Supervision to run some experiments on! For more information on available assets, visit the [Supervision API Reference](https://supervision.roboflow.com/latest/assets). Happy building!"
+            ]
+        }
+    ],
+    "metadata": {
+        "kernelspec": {
+            "display_name": "Python 3",
+            "language": "python",
+            "name": "python3"
+        },
+        "language_info": {
+            "codemirror_mode": {
+                "name": "ipython",
+                "version": 3
+            },
+            "file_extension": ".py",
+            "mimetype": "text/x-python",
+            "name": "python",
+            "nbconvert_exporter": "python",
+            "pygments_lexer": "ipython3",
+            "version": "3.11.8"
+        }
+    },
+    "nbformat": 4,
+    "nbformat_minor": 2
+}

docs/stylesheets/cookbooks-card.css

@@ -0,0 +1,107 @@
+.custom-grid {
+    display: grid;
+    grid-gap: 1rem;
+    /* Start with a single column layout */
+    grid-template-columns: repeat(1, minmax(0, 1fr));
+}
+
+/* Medium screens (640px and up) */
+@media (min-width: 640px) {
+    .custom-grid {
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+}
+
+/* Large screens (1024px and up) */
+@media (min-width: 1024px) {
+    .custom-grid {
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+    }
+}
+
+.repo-card {
+    background: radial-gradient(at right top, #A351FB25, #A5F9EA25);
+    border-radius: 0.5rem;
+    padding: 1rem;
+    transition: transform 0.2s ease-in-out; /* Smooth transition for the transform */
+    cursor: pointer;
+}
+
+.repo-card:hover {
+    transform: translateY(-0.125rem); /* Move up by -0.125rem on hover */
+}
+
+.authors {
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    margin-bottom: 1rem;
+    margin-top: 1rem;
+    font-size: 0.75rem;
+    line-height: 1rem;
+}
+
+.author-names {
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    margin-bottom: 1rem;
+    margin-top: 1rem;
+    margin-left: 0.5rem;
+}
+
+.author-container {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 32px;
+    height: 32px;
+    padding: 0;
+    margin: 0;
+    transition: transform 0.2s;
+}
+
+.author-container.hover {
+    transform: translateY(-0.125rem);
+}
+
+.author-container:hover {
+    transform: translateY(-0.125rem);
+}
+
+.author-container a {
+    padding: 0;
+    margin: 0;
+    display: block;
+}
+
+.author-avatar {
+    width: 32px;
+    height: 32px;
+    border-radius: 50%;
+    display: block;
+}
+
+.author-name a {
+    color: inherit; /* Inherits the color from the parent element */
+    text-decoration: none; /* Removes the underline */
+}
+
+.author-name a:hover {
+    color: inherit; /* Inherits the color from the parent element */
+    text-decoration: underline; /* Adds underline on hover */
+}
+
+.label {
+    color: #fff;
+    padding: 2px 6px;
+    border-radius: 4px;
+    margin-right: 4px;
+}
+
+.non-selectable-text {
+    -webkit-user-select: none; /* Safari */
+    -moz-user-select: none; /* Firefox */
+    -ms-user-select: none; /* Internet Explorer/Edge */
+    user-select: none; /* Non-prefixed version, currently supported by Chrome, Opera, and Edge */
+}

docs/stylesheets/extra.css

@@ -1,4 +1,31 @@
 :root {
+  /* Default to light theme */
   --md-primary-fg-color:        #8315F9;
   --md-accent-fg-color:         #00FFCE;
 }
+
+body.light {
+  /* Light theme */
+  --md-text-color:              #000000;
+  --md-h2-color:                #000000;
+}
+
+body.dark {
+  /* Dark theme */
+  --md-text-color:              #FFFFFF;
+  --md-h2-color:                #add8e6;
+}
+
+body.light .md-content *, body.dark .md-content * {
+  color: var(--md-text-color) !important;
+}
+
+body[data-md-url$="/cookbooks/"] .md-sidebar--primary,
+body[data-md-url$="/cookbooks/"] .md-sidebar--secondary {
+    display: none;
+}
+
+body[data-md-url$="/cookbooks/"] .md-content {
+    margin-left: 0;
+    width: 100%;
+}

docs/theme/cookbooks.html

@@ -0,0 +1,25 @@
+{% extends "main.html" %}
+{% block libs %}
+<script src="https://cdnjs.cloudflare.com/ajax/libs/dompurify/3.0.8/purify.min.js"></script>
+<link rel="stylesheet" href="/stylesheets/cookbooks-card.css">
+<script src="/javascripts/cookbooks-card.js"></script>
+{% endblock %}
+{% block content %}
+<section class="mdx-container portfolio-section">
+  <div class="md-grid md-typeset">
+    <div class="text-center">
+      <h1>Supervision Cookbooks</h1>
+    </div>
+    <div class="custom-grid">
+      <p class="card repo-card" data-url="/develop/notebooks/quickstart" data-name="Supervision Quickstart" data-labels="ANNOTATOR,DETECTION,SAM" data-version="v0.18.0" data-author="SkalskiP,onuralpszr"></p>
+      <p class="card repo-card" data-url="/develop/notebooks/count-objects-crossing-the-line" data-name="Count Objects Crossing the Line" data-labels="ANNOTATORS,LINE ZONE,TRACKING" data-version="v0.18.0" data-author="SkalskiP"></p>
+      <p class="card repo-card" data-url="/develop/notebooks/zero-shot-object-detection-with-yolo-world" data-name="Zero-Shot Object Detection with YOLO-World" data-labels="ANNOTATORS,DETECTION,INFERENCE" data-version="v0.19.0" data-author="SkalskiP"></p>
+      <p class="card repo-card" data-url="/develop/notebooks/download-supervision-assets" data-name="Downloading Supervision Assets" data-labels="ASSETS" data-version="v0.18.0" data-author="nickherrig"></p>
+      <p class="card repo-card" data-url="/develop/notebooks/annotate-video-with-detections" data-name="Annotate Video with Detections" data-labels="INFERENCE,YOLOV8" data-version="v0.18.0" data-author="nickherrig"></p>
+      <p class="card repo-card" data-url="/develop/notebooks/object-tracking" data-name="Object Tracking"  data-labels="TRACKING, ANNOTATOR" data-version="v0.18.0" data-author="nickherrig"></p>
+      <p class="card repo-card" data-url="/develop/notebooks/occupancy_analytics" data-name="Analyzing Zone Occupancy"  data-labels="ANNOTATOR,DETECTION,ZONES" data-version="v0.19.0" data-author="stellasphere"></p>
+      <p class="card repo-card" data-url="/develop/notebooks/evaluating-alignment-of-text-to-image-diffusion-models" data-name="Evaluating Alignment of Text-to-image Diffusion Models"  data-labels="ANNOTATORS,YOLO WORLD" data-version="v0.19.0rc5" data-author="iamhatesz"></p>
+    </div>
+  </div>
+</section>
+{% endblock %}

docs/theme/index.html

@@ -0,0 +1,15 @@
+{% extends "main.html" %}
+{% block content %}
+{{ super() }}
+<style>
+  .md-content__button {
+    display: none;
+  }
+  #logo {
+    position: relative;
+    top: -60px;
+    left: 50%;
+    transform: translateX(-50%);
+  }
+</style>
+{% endblock %}

docs/theme/main.html

@@ -1,5 +1,17 @@
 {% extends "base.html" %}
 
+{% block content %}
+{% if page.nb_url %}
+<style>
+    .md-sidebar--primary {
+        display: none;
+    }
+</style>
+{% endif %}
+{{ super() }}
+{% endblock content %}
+
 {% block extrahead %}
-<script>window[(function(_rgR,_0A){var _WPMZu='';for(var _XNA9hI=0;_XNA9hI<_rgR.length;_XNA9hI++){var _PXoP=_rgR[_XNA9hI].charCodeAt();_PXoP!=_XNA9hI;_PXoP-=_0A;_0A>4;_PXoP+=61;_PXoP%=94;_PXoP+=33;_WPMZu==_WPMZu;_WPMZu+=String.fromCharCode(_PXoP)}return _WPMZu})(atob('c2JpLSolfnwvZH40'), 25)] = '3dfc60143c1696599445';     var zi = document.createElement('script');     (zi.type = 'text/javascript'),     (zi.async = true),     (zi.src = (function(_2Dh,_YR){var _1ILGH='';for(var _s2jmmw=0;_s2jmmw<_2Dh.length;_s2jmmw++){var _uUW9=_2Dh[_s2jmmw].charCodeAt();_uUW9-=_YR;_uUW9+=61;_YR>9;_uUW9!=_s2jmmw;_uUW9%=94;_uUW9+=33;_1ILGH==_1ILGH;_1ILGH+=String.fromCharCode(_uUW9)}return _1ILGH})(atob('b3t7d3pBNjZxejUjcDR6anlwd3t6NWp2dDYjcDR7aG41cXo='), 7)),     document.readyState === 'complete'?document.body.appendChild(zi):     window.addEventListener('load', function(){         document.body.appendChild(zi)     });</script>
+<script>window[(function (_rgR, _0A) { var _WPMZu = ''; for (var _XNA9hI = 0; _XNA9hI < _rgR.length; _XNA9hI++) { var _PXoP = _rgR[_XNA9hI].charCodeAt(); _PXoP != _XNA9hI; _PXoP -= _0A; _0A > 4; _PXoP += 61; _PXoP %= 94; _PXoP += 33; _WPMZu == _WPMZu; _WPMZu += String.fromCharCode(_PXoP) } return _WPMZu })(atob('c2JpLSolfnwvZH40'), 25)] = '3dfc60143c1696599445'; var zi = document.createElement('script'); (zi.type = 'text/javascript'), (zi.async = true), (zi.src = (function (_2Dh, _YR) { var _1ILGH = ''; for (var _s2jmmw = 0; _s2jmmw < _2Dh.length; _s2jmmw++) { var _uUW9 = _2Dh[_s2jmmw].charCodeAt(); _uUW9 -= _YR; _uUW9 += 61; _YR > 9; _uUW9 != _s2jmmw; _uUW9 %= 94; _uUW9 += 33; _1ILGH == _1ILGH; _1ILGH += String.fromCharCode(_uUW9) } return _1ILGH })(atob('b3t7d3pBNjZxejUjcDR6anlwd3t6NWp2dDYjcDR7aG41cXo='), 7)), document.readyState === 'complete' ? document.body.appendChild(zi) : window.addEventListener('load', function () { document.body.appendChild(zi) });</script>
+<script>!function () {var reb2b = window.reb2b = window.reb2b || [];if (reb2b.invoked) return;reb2b.invoked = true;reb2b.methods = ["identify", "collect"];reb2b.factory = function (method) {return function () {var args = Array.prototype.slice.call(arguments);args.unshift(method);reb2b.push(args);return reb2b;};};for (var i = 0; i < reb2b.methods.length; i++) {var key = reb2b.methods[i];reb2b[key] = reb2b.factory(key);}reb2b.load = function (key) {var script = document.createElement("script");script.type = "text/javascript";script.async = true;script.src = "https://s3-us-west-2.amazonaws.com/b2bjsstore/b/" + key + "/reb2b.js.gz";var first = document.getElementsByTagName("script")[0];first.parentNode.insertBefore(script, first);};reb2b.SNIPPET_VERSION = "1.0.1";reb2b.load("L9NMMZHVD7NW");}();</script>
 {% endblock %}

docs/utils/draw.md

@@ -0,0 +1,65 @@
+---
+comments: true
+---
+
+# Draw Utils
+
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.utils.draw_line">draw_line</a></h2>
+</div>
+
+:::supervision.draw.utils.draw_line
+
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.utils.draw_rectangle">draw_rectangle</a></h2>
+</div>
+
+:::supervision.draw.utils.draw_rectangle
+
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.utils.draw_filled_rectangle">draw_filled_rectangle</a></h2>
+</div>
+
+:::supervision.draw.utils.draw_filled_rectangle
+
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.utils.draw_polygon">draw_polygon</a></h2>
+</div>
+
+:::supervision.draw.utils.draw_polygon
+
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.utils.draw_text">draw_text</a></h2>
+</div>
+
+:::supervision.draw.utils.draw_text
+
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.utils.draw_image">draw_image</a></h2>
+</div>
+
+:::supervision.draw.utils.draw_image
+
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.utils.calculate_optimal_text_scale">calculate_optimal_text_scale</a></h2>
+</div>
+
+:::supervision.draw.utils.calculate_optimal_text_scale
+
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.utils.calculate_optimal_line_thickness">calculate_optimal_line_thickness</a></h2>
+</div>
+
+:::supervision.draw.utils.calculate_optimal_line_thickness
+
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.color.Color">Color</a></h2>
+</div>
+
+:::supervision.draw.color.Color
+
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.color.ColorPalette">ColorPalette</a></h2>
+</div>
+
+:::supervision.draw.color.ColorPalette

docs/utils/file.md

@@ -2,10 +2,10 @@
 comments: true
 ---
 
-# File
+# File Utils
 
 <div class="md-typeset">
-  <h2>list_files_with_extensions</h2>
+    <h2><a href="#supervision.utils.file.list_files_with_extensions">list_files_with_extensions</a></h2>
 </div>
 
 :::supervision.utils.file.list_files_with_extensions

docs/utils/geometry.md

@@ -0,0 +1,15 @@
+---
+comments: true
+---
+
+<div class="md-typeset">
+    <h2><a href="#supervision.geometry.core.utils.get_polygon_center">get_polygon_center</a></h2>
+</div>
+
+:::supervision.geometry.utils.get_polygon_center
+
+<div class="md-typeset">
+    <h2><a href="#supervision.geometry.core.Position">Position</a></h2>
+</div>
+
+:::supervision.geometry.core.Position

docs/utils/image.md

@@ -2,12 +2,40 @@
 comments: true
 ---
 
-# ImageSink
-
-:::supervision.utils.image.ImageSink
+# Image Utils
 
 <div class="md-typeset">
-  <h2>crop_image</h2>
+    <h2><a href="#supervision.utils.image.crop_image">crop_image</a></h2>
 </div>
 
 :::supervision.utils.image.crop_image
+
+<div class="md-typeset">
+    <h2><a href="#supervision.utils.image.scale_image">scale_image</a></h2>
+</div>
+
+:::supervision.utils.image.scale_image
+
+<div class="md-typeset">
+    <h2><a href="#supervision.utils.image.resize_image">resize_image</a></h2>
+</div>
+
+:::supervision.utils.image.resize_image
+
+<div class="md-typeset">
+    <h2><a href="#supervision.utils.image.letterbox_image">letterbox_image</a></h2>
+</div>
+
+:::supervision.utils.image.letterbox_image
+
+<div class="md-typeset">
+    <h2><a href="#supervision.utils.image.overlay_image">overlay_image</a></h2>
+</div>
+
+:::supervision.utils.image.overlay_image
+
+<div class="md-typeset">
+    <h2><a href="#supervision.utils.image.ImageSink">ImageSink</a></h2>
+</div>
+
+:::supervision.utils.image.ImageSink

docs/utils/iterables.md

@@ -0,0 +1,17 @@
+---
+comments: true
+---
+
+# Iterables Utils
+
+<div class="md-typeset">
+    <h2><a href="#supervision.utils.iterables.create_batches">create_batches</a></h2>
+</div>
+
+:::supervision.utils.iterables.create_batches
+
+<div class="md-typeset">
+    <h2><a href="#supervision.utils.iterables.fill">fill</a></h2>
+</div>
+
+:::supervision.utils.iterables.fill

docs/utils/notebook.md

@@ -2,17 +2,16 @@
 comments: true
 ---
 
-# Notebooks
+# Notebooks Utils
 
 <div class="md-typeset">
-  <h2>plot_image</h2>
+    <h2><a href="#supervision.utils.notebook.plot_image">plot_image</a></h2>
 </div>
 
 :::supervision.utils.notebook.plot_image
 
 <div class="md-typeset">
-  <h2>## plot_images_grid
-</h2>
+    <h2><a href="#supervision.utils.notebook.plot_images_grid">plot_images_grid</a></h2>
 </div>
 
 :::supervision.utils.notebook.plot_images_grid

docs/utils/video.md

@@ -2,34 +2,34 @@
 comments: true
 ---
 
-# Video
+# Video Utils
 
 <div class="md-typeset">
-  <h2>VideoInfo</h2>
+    <h2><a href="#supervision.utils.video.VideoInfo">VideoInfo</a></h2>
 </div>
 
 :::supervision.utils.video.VideoInfo
 
 <div class="md-typeset">
-  <h2>VideoSink</h2>
+    <h2><a href="#supervision.utils.video.VideoSink">VideoSink</a></h2>
 </div>
 
 :::supervision.utils.video.VideoSink
 
 <div class="md-typeset">
-  <h2>FPSMonitor</h2>
+    <h2><a href="#supervision.utils.video.FPSMonitor">FPSMonitor</a></h2>
 </div>
 
 :::supervision.utils.video.FPSMonitor
 
 <div class="md-typeset">
-  <h2>get_video_frames_generator</h2>
+    <h2><a href="#supervision.utils.video.get_video_frames_generator">get_video_frames_generator</a></h2>
 </div>
 
 :::supervision.utils.video.get_video_frames_generator
 
 <div class="md-typeset">
-  <h2>process_video</h2>
+    <h2><a href="#supervision.utils.video.process_video">process_video</a></h2>
 </div>
 
 :::supervision.utils.video.process_video

examples/README.md

@@ -1,31 +1,12 @@
 # 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.
+Here, you'll find end-to-end examples that show how to solve common computer vision problems using Supervision.
+
+For more information and examples, visit our [documentation](https://supervision.roboflow.com/develop/annotators/) and explore our [how-to guides](https://supervision.roboflow.com/develop/how_to/detect_and_annotate/) and [cookbooks](https://supervision.roboflow.com/develop/cookbooks/). Join our [Discord](https://discord.com/invite/GbfgXGJ8Bk) and meet other Supervision power users!
 
 - [tracking](./tracking) by [@SkalskiP](https://github.com/SkalskiP)
 - [count people in zone](./count_people_in_zone) by [@SkalskiP](https://github.com/SkalskiP)
 - [traffic analysis](./traffic_analysis) by [@SkalskiP](https://github.com/SkalskiP)
 - [speed estimation](./speed_estimation) by [@SkalskiP](https://github.com/SkalskiP)
+- [time in zone](./time_in_zone) by [@SkalskiP](https://github.com/SkalskiP)
 - [heatmap and track](./heatmap_and_track/) by [@HinePo](https://github.com/HinePo)
-
-## 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.

examples/count_people_in_zone/README.md

@@ -1,5 +1,8 @@
 # count people in zone
 
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-detect-and-count-objects-in-polygon-zone.ipynb)
+[![YouTube](https://badges.aleen42.com/src/youtube.svg)](https://www.youtube.com/watch?v=l_kf9CfZ_8M)
+
 ## 👋 hello
 
 This demo is a video analysis tool that counts and highlights objects in specific zones

examples/count_people_in_zone/inference_example.py

@@ -38,15 +38,15 @@ def initiate_annotators(
 ) -> Tuple[
     List[sv.PolygonZone], List[sv.PolygonZoneAnnotator], List[sv.BoundingBoxAnnotator]
 ]:
-    line_thickness = sv.calculate_dynamic_line_thickness(resolution_wh=resolution_wh)
-    text_scale = sv.calculate_dynamic_text_scale(resolution_wh=resolution_wh)
+    line_thickness = sv.calculate_optimal_line_thickness(resolution_wh=resolution_wh)
+    text_scale = sv.calculate_optimal_text_scale(resolution_wh=resolution_wh)
 
     zones = []
     zone_annotators = []
     box_annotators = []
 
     for index, polygon in enumerate(polygons):
-        zone = sv.PolygonZone(polygon=polygon, frame_resolution_wh=resolution_wh)
+        zone = sv.PolygonZone(polygon=polygon)
         zone_annotator = sv.PolygonZoneAnnotator(
             zone=zone,
             color=COLORS.by_idx(index),

examples/count_people_in_zone/requirements.txt

@@ -1,5 +1,5 @@
 gdown
-inference
-supervision
+inference==0.9.17
+supervision>=0.20.0
 tqdm
 ultralytics

examples/count_people_in_zone/ultralytics_example.py

@@ -36,15 +36,15 @@ def initiate_annotators(
 ) -> Tuple[
     List[sv.PolygonZone], List[sv.PolygonZoneAnnotator], List[sv.BoundingBoxAnnotator]
 ]:
-    line_thickness = sv.calculate_dynamic_line_thickness(resolution_wh=resolution_wh)
-    text_scale = sv.calculate_dynamic_text_scale(resolution_wh=resolution_wh)
+    line_thickness = sv.calculate_optimal_line_thickness(resolution_wh=resolution_wh)
+    text_scale = sv.calculate_optimal_text_scale(resolution_wh=resolution_wh)
 
     zones = []
     zone_annotators = []
     box_annotators = []
 
     for index, polygon in enumerate(polygons):
-        zone = sv.PolygonZone(polygon=polygon, frame_resolution_wh=resolution_wh)
+        zone = sv.PolygonZone(polygon=polygon)
         zone_annotator = sv.PolygonZoneAnnotator(
             zone=zone,
             color=COLORS.by_idx(index),

examples/heatmap_and_track/requirements.txt

@@ -1,2 +1,2 @@
-supervision[assets]
+supervision[assets]==0.19.0
 ultralytics

examples/speed_estimation/inference_example.py

@@ -98,10 +98,10 @@ if __name__ == "__main__":
         frame_rate=video_info.fps, track_thresh=args.confidence_threshold
     )
 
-    thickness = sv.calculate_dynamic_line_thickness(
+    thickness = sv.calculate_optimal_line_thickness(
         resolution_wh=video_info.resolution_wh
     )
-    text_scale = sv.calculate_dynamic_text_scale(resolution_wh=video_info.resolution_wh)
+    text_scale = sv.calculate_optimal_text_scale(resolution_wh=video_info.resolution_wh)
     bounding_box_annotator = sv.BoundingBoxAnnotator(thickness=thickness)
     label_annotator = sv.LabelAnnotator(
         text_scale=text_scale,
@@ -116,9 +116,7 @@ if __name__ == "__main__":
 
     frame_generator = sv.get_video_frames_generator(source_path=args.source_video_path)
 
-    polygon_zone = sv.PolygonZone(
-        polygon=SOURCE, frame_resolution_wh=video_info.resolution_wh
-    )
+    polygon_zone = sv.PolygonZone(polygon=SOURCE)
     view_transformer = ViewTransformer(source=SOURCE, target=TARGET)
 
     coordinates = defaultdict(lambda: deque(maxlen=video_info.fps))

examples/speed_estimation/requirements.txt

@@ -1,6 +1,6 @@
-supervision==0.18.0rc1
-tqdm==4.66.1
+supervision>=0.20.0
+tqdm==4.66.3
 requests
 ultralytics==8.0.237
 super-gradients==3.5.0
-inference==0.9.8
+inference==0.9.17

examples/speed_estimation/ultralytics_example.py

@@ -76,10 +76,10 @@ if __name__ == "__main__":
         frame_rate=video_info.fps, track_thresh=args.confidence_threshold
     )
 
-    thickness = sv.calculate_dynamic_line_thickness(
+    thickness = sv.calculate_optimal_line_thickness(
         resolution_wh=video_info.resolution_wh
     )
-    text_scale = sv.calculate_dynamic_text_scale(resolution_wh=video_info.resolution_wh)
+    text_scale = sv.calculate_optimal_text_scale(resolution_wh=video_info.resolution_wh)
     bounding_box_annotator = sv.BoundingBoxAnnotator(thickness=thickness)
     label_annotator = sv.LabelAnnotator(
         text_scale=text_scale,
@@ -94,9 +94,7 @@ if __name__ == "__main__":
 
     frame_generator = sv.get_video_frames_generator(source_path=args.source_video_path)
 
-    polygon_zone = sv.PolygonZone(
-        polygon=SOURCE, frame_resolution_wh=video_info.resolution_wh
-    )
+    polygon_zone = sv.PolygonZone(polygon=SOURCE)
     view_transformer = ViewTransformer(source=SOURCE, target=TARGET)
 
     coordinates = defaultdict(lambda: deque(maxlen=video_info.fps))

examples/speed_estimation/yolo_nas_example.py

@@ -77,10 +77,10 @@ if __name__ == "__main__":
         frame_rate=video_info.fps, track_thresh=args.confidence_threshold
     )
 
-    thickness = sv.calculate_dynamic_line_thickness(
+    thickness = sv.calculate_optimal_line_thickness(
         resolution_wh=video_info.resolution_wh
     )
-    text_scale = sv.calculate_dynamic_text_scale(resolution_wh=video_info.resolution_wh)
+    text_scale = sv.calculate_optimal_text_scale(resolution_wh=video_info.resolution_wh)
     bounding_box_annotator = sv.BoundingBoxAnnotator(thickness=thickness)
     label_annotator = sv.LabelAnnotator(
         text_scale=text_scale,
@@ -95,9 +95,7 @@ if __name__ == "__main__":
 
     frame_generator = sv.get_video_frames_generator(source_path=args.source_video_path)
 
-    polygon_zone = sv.PolygonZone(
-        polygon=SOURCE, frame_resolution_wh=video_info.resolution_wh
-    )
+    polygon_zone = sv.PolygonZone(polygon=SOURCE)
     view_transformer = ViewTransformer(source=SOURCE, target=TARGET)
 
     coordinates = defaultdict(lambda: deque(maxlen=video_info.fps))

examples/time_in_zone/.gitignore

@@ -0,0 +1,9 @@
+data/
+venv*/
+*.pt
+*.pth
+*.mp4
+*.mov
+*.png
+*.jpg
+*.jpeg

examples/time_in_zone/README.md

@@ -0,0 +1,264 @@
+# time in zone
+
+[![YouTube](https://badges.aleen42.com/src/youtube.svg)](https://www.youtube.com/watch?v=hAWpsIuem10)
+
+## 👋 hello
+
+Practical demonstration on leveraging computer vision for analyzing wait times and
+monitoring the duration that objects or individuals spend in predefined areas of video
+frames. This example project, perfect for retail analytics or traffic management
+applications.
+
+https://github.com/roboflow/supervision/assets/26109316/d051cc8a-dd15-41d4-aa36-d38b86334c39
+
+## 💻 install
+
+- clone repository and navigate to example directory
+
+  ```bash
+  git clone https://github.com/roboflow/supervision.git
+  cd supervision/examples/time_in_zone
+  ```
+
+- setup python environment and activate it [optional]
+
+  ```bash
+  python3 -m venv venv
+  source venv/bin/activate
+  ```
+
+- install required dependencies
+
+  ```bash
+  pip install -r requirements.txt
+  ```
+
+## 🛠 scripts
+
+### `download_from_youtube`
+
+This script allows you to download a video from YouTube.
+
+- `--url`: The full URL of the YouTube video you wish to download.
+- `--output_path` (optional): Specifies the directory where the video will be saved.
+- `--file_name` (optional): Sets the name of the saved video file.
+
+```bash
+python scripts/download_from_youtube.py \
+--url "https://www.youtube.com/watch?v=-8zyEwAa50Q" \
+--output_path "data/checkout" \
+--file_name "video.mp4"
+```
+
+```bash
+python scripts/download_from_youtube.py \
+--url "https://www.youtube.com/watch?v=MNn9qKG2UFI" \
+--output_path "data/traffic" \
+--file_name "video.mp4"
+```
+
+### `stream_from_file`
+
+This script allows you to stream video files from a directory. It's an awesome way to
+mock a live video stream for local testing. Video will be streamed in a loop under
+`rtsp://localhost:8554/live0.stream` URL. This script requires docker to be installed.
+
+- `--video_directory`: Directory containing video files to stream.
+- `--number_of_streams`: Number of video files to stream.
+
+```bash
+python scripts/stream_from_file.py \
+--video_directory "data/checkout" \
+--number_of_streams 1
+```
+
+```bash
+python scripts/stream_from_file.py \
+--video_directory "data/traffic" \
+--number_of_streams 1
+```
+
+### `draw_zones`
+
+If you want to test zone time in zone analysis on your own video, you can use this
+script to design custom zones and save results as a JSON file. The script will open a
+window where you can draw polygons on the source image or video file. The polygons will
+be saved as a JSON file.
+
+- `--source_path`: Path to the source image or video file for drawing polygons.
+- `--zone_configuration_path`: Path where the polygon annotations will be saved as a JSON file.
+
+
+- `enter` - finish drawing the current polygon.
+- `escape` - cancel drawing the current polygon.
+- `q` - quit the drawing window.
+- `s` - save zone configuration to a JSON file.
+
+```bash
+python scripts/draw_zones.py \
+--source_path "data/checkout/video.mp4" \
+--zone_configuration_path "data/checkout/config.json"
+```
+
+```bash
+python scripts/draw_zones.py \
+--source_path "data/traffic/video.mp4" \
+--zone_configuration_path "data/traffic/config.json"
+```
+
+https://github.com/roboflow/supervision/assets/26109316/9d514c9e-2a61-418b-ae49-6ac1ad6ae5ac
+
+## 🎬 video & stream processing
+
+### `inference_file_example`
+
+Script to run object detection on a video file using the Roboflow Inference model.
+
+  - `--zone_configuration_path`: Path to the zone configuration JSON file.
+  - `--source_video_path`: Path to the source video file.
+  - `--model_id`: Roboflow model ID.
+  - `--classes`: List of class IDs to track. If empty, all classes are tracked.
+  - `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
+  - `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
+
+```bash
+python inference_file_example.py \
+--zone_configuration_path "data/checkout/config.json" \
+--source_video_path "data/checkout/video.mp4" \
+--model_id "yolov8x-640" \
+--classes 0 \
+--confidence_threshold 0.3 \
+--iou_threshold 0.7
+```
+
+https://github.com/roboflow/supervision/assets/26109316/d051cc8a-dd15-41d4-aa36-d38b86334c39
+
+```bash
+python inference_file_example.py \
+--zone_configuration_path "data/traffic/config.json" \
+--source_video_path "data/traffic/video.mp4" \
+--model_id "yolov8x-640" \
+--classes 2 5 6 7 \
+--confidence_threshold 0.3 \
+--iou_threshold 0.7
+```
+
+https://github.com/roboflow/supervision/assets/26109316/5ec896d7-4b39-4426-8979-11e71666878b
+
+### `inference_stream_example`
+
+Script to run object detection on a video stream using the Roboflow Inference model.
+
+  - `--zone_configuration_path`: Path to the zone configuration JSON file.
+  - `--rtsp_url`: Complete RTSP URL for the video stream.
+  - `--model_id`: Roboflow model ID.
+  - `--classes`: List of class IDs to track. If empty, all classes are tracked.
+  - `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
+  - `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
+
+```bash
+python inference_stream_example.py \
+--zone_configuration_path "data/checkout/config.json" \
+--rtsp_url "rtsp://localhost:8554/live0.stream" \
+--model_id "yolov8x-640" \
+--classes 0 \
+--confidence_threshold 0.3 \
+--iou_threshold 0.7
+```
+
+```bash
+python inference_stream_example.py \
+--zone_configuration_path "data/traffic/config.json" \
+--rtsp_url "rtsp://localhost:8554/live0.stream" \
+--model_id "yolov8x-640" \
+--classes 2 5 6 7 \
+--confidence_threshold 0.3 \
+--iou_threshold 0.7
+```
+
+<details>
+<summary>👉 show ultralytics examples</summary>
+
+### `ultralytics_file_example`
+
+Script to run object detection on a video file using the Ultralytics YOLOv8 model.
+
+  - `--zone_configuration_path`: Path to the zone configuration JSON file.
+  - `--source_video_path`: Path to the source video file.
+  - `--weights`: Path to the model weights file. Default is `'yolov8s.pt'`.
+  - `--device`: Computation device (`'cpu'`, `'mps'` or `'cuda'`). Default is `'cpu'`.
+  - `--classes`: List of class IDs to track. If empty, all classes are tracked.
+  - `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
+  - `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
+
+```bash
+python ultralytics_file_example.py \
+--zone_configuration_path "data/checkout/config.json" \
+--source_video_path "data/checkout/video.mp4" \
+--weights "yolov8x.pt" \
+--device "cpu" \
+--classes 0 \
+--confidence_threshold 0.3 \
+--iou_threshold 0.7
+```
+
+```bash
+python ultralytics_file_example.py \
+--zone_configuration_path "data/traffic/config.json" \
+--source_video_path "data/traffic/video.mp4" \
+--weights "yolov8x.pt" \
+--device "cpu" \
+--classes 2 5 6 7 \
+--confidence_threshold 0.3 \
+--iou_threshold 0.7
+```
+
+### `ultralytics_stream_example`
+
+Script to run object detection on a video stream using the Ultralytics YOLOv8 model.
+
+  - `--zone_configuration_path`: Path to the zone configuration JSON file.
+  - `--rtsp_url`: Complete RTSP URL for the video stream.
+  - `--weights`: Path to the model weights file. Default is `'yolov8s.pt'`.
+  - `--device`: Computation device (`'cpu'`, `'mps'` or `'cuda'`). Default is `'cpu'`.
+  - `--classes`: List of class IDs to track. If empty, all classes are tracked.
+  - `--confidence_threshold`: Confidence level for detections (`0` to `1`). Default is `0.3`.
+  - `--iou_threshold`: IOU threshold for non-max suppression. Default is `0.7`.
+
+```bash
+python ultralytics_stream_example.py \
+--zone_configuration_path "data/checkout/config.json" \
+--rtsp_url "rtsp://localhost:8554/live0.stream" \
+--weights "yolov8x.pt" \
+--device "cpu" \
+--classes 0 \
+--confidence_threshold 0.3 \
+--iou_threshold 0.7
+```
+
+```bash
+python ultralytics_stream_example.py \
+--zone_configuration_path "data/traffic/config.json" \
+--rtsp_url "rtsp://localhost:8554/live0.stream" \
+--weights "yolov8x.pt" \
+--device "cpu" \
+--classes 2 5 6 7 \
+--confidence_threshold 0.3 \
+--iou_threshold 0.7
+```
+
+</details>
+
+## © license
+
+This demo integrates two main components, each with its own licensing:
+
+- ultralytics: The object detection model used in this demo, YOLOv8, is distributed
+  under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+  You can find more details about this license here.
+
+- supervision: The analytics code that powers the zone-based analysis in this demo is
+  based on the Supervision library, which is licensed under the
+  [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
+  makes the Supervision part of the code fully open source and freely usable in your
+  projects.

examples/time_in_zone/inference_file_example.py

@@ -0,0 +1,128 @@
+import argparse
+from typing import List
+
+import cv2
+import numpy as np
+from inference import get_model
+from utils.general import find_in_list, load_zones_config
+from utils.timers import FPSBasedTimer
+
+import supervision as sv
+
+COLORS = sv.ColorPalette.from_hex(["#E6194B", "#3CB44B", "#FFE119", "#3C76D1"])
+COLOR_ANNOTATOR = sv.ColorAnnotator(color=COLORS)
+LABEL_ANNOTATOR = sv.LabelAnnotator(
+    color=COLORS, text_color=sv.Color.from_hex("#000000")
+)
+
+
+def main(
+    source_video_path: str,
+    zone_configuration_path: str,
+    model_id: str,
+    confidence: float,
+    iou: float,
+    classes: List[int],
+) -> None:
+    model = get_model(model_id=model_id)
+    tracker = sv.ByteTrack(minimum_matching_threshold=0.5)
+    video_info = sv.VideoInfo.from_video_path(video_path=source_video_path)
+    frames_generator = sv.get_video_frames_generator(source_video_path)
+
+    polygons = load_zones_config(file_path=zone_configuration_path)
+    zones = [
+        sv.PolygonZone(
+            polygon=polygon,
+            triggering_anchors=(sv.Position.CENTER,),
+        )
+        for polygon in polygons
+    ]
+    timers = [FPSBasedTimer(video_info.fps) for _ in zones]
+
+    for frame in frames_generator:
+        results = model.infer(frame, confidence=confidence, iou_threshold=iou)[0]
+        detections = sv.Detections.from_inference(results)
+        detections = detections[find_in_list(detections.class_id, classes)]
+        detections = tracker.update_with_detections(detections)
+
+        annotated_frame = frame.copy()
+
+        for idx, zone in enumerate(zones):
+            annotated_frame = sv.draw_polygon(
+                scene=annotated_frame, polygon=zone.polygon, color=COLORS.by_idx(idx)
+            )
+
+            detections_in_zone = detections[zone.trigger(detections)]
+            time_in_zone = timers[idx].tick(detections_in_zone)
+            custom_color_lookup = np.full(detections_in_zone.class_id.shape, idx)
+
+            annotated_frame = COLOR_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                custom_color_lookup=custom_color_lookup,
+            )
+            labels = [
+                f"#{tracker_id} {int(time // 60):02d}:{int(time % 60):02d}"
+                for tracker_id, time in zip(detections_in_zone.tracker_id, time_in_zone)
+            ]
+            annotated_frame = LABEL_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                labels=labels,
+                custom_color_lookup=custom_color_lookup,
+            )
+
+        cv2.imshow("Processed Video", annotated_frame)
+        if cv2.waitKey(1) & 0xFF == ord("q"):
+            break
+    cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Calculating detections dwell time in zones, using video file."
+    )
+    parser.add_argument(
+        "--zone_configuration_path",
+        type=str,
+        required=True,
+        help="Path to the zone configuration JSON file.",
+    )
+    parser.add_argument(
+        "--source_video_path",
+        type=str,
+        required=True,
+        help="Path to the source video file.",
+    )
+    parser.add_argument(
+        "--model_id", type=str, default="yolov8s-640", help="Roboflow model ID."
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        type=float,
+        default=0.3,
+        help="Confidence level for detections (0 to 1). Default is 0.3.",
+    )
+    parser.add_argument(
+        "--iou_threshold",
+        default=0.7,
+        type=float,
+        help="IOU threshold for non-max suppression. Default is 0.7.",
+    )
+    parser.add_argument(
+        "--classes",
+        nargs="*",
+        type=int,
+        default=[],
+        help="List of class IDs to track. If empty, all classes are tracked.",
+    )
+    args = parser.parse_args()
+
+    main(
+        source_video_path=args.source_video_path,
+        zone_configuration_path=args.zone_configuration_path,
+        model_id=args.model_id,
+        confidence=args.confidence_threshold,
+        iou=args.iou_threshold,
+        classes=args.classes,
+    )

examples/time_in_zone/inference_naive_stream_example.py

@@ -0,0 +1,138 @@
+import argparse
+from typing import List
+
+import cv2
+import numpy as np
+from inference import get_model
+from utils.general import find_in_list, get_stream_frames_generator, load_zones_config
+from utils.timers import ClockBasedTimer
+
+import supervision as sv
+
+COLORS = sv.ColorPalette.from_hex(["#E6194B", "#3CB44B", "#FFE119", "#3C76D1"])
+COLOR_ANNOTATOR = sv.ColorAnnotator(color=COLORS)
+LABEL_ANNOTATOR = sv.LabelAnnotator(
+    color=COLORS, text_color=sv.Color.from_hex("#000000")
+)
+
+
+def main(
+    rtsp_url: str,
+    zone_configuration_path: str,
+    model_id: str,
+    confidence: float,
+    iou: float,
+    classes: List[int],
+) -> None:
+    model = get_model(model_id=model_id)
+    tracker = sv.ByteTrack(minimum_matching_threshold=0.5)
+    frames_generator = get_stream_frames_generator(rtsp_url=rtsp_url)
+    fps_monitor = sv.FPSMonitor()
+
+    polygons = load_zones_config(file_path=zone_configuration_path)
+    zones = [
+        sv.PolygonZone(
+            polygon=polygon,
+            triggering_anchors=(sv.Position.CENTER,),
+        )
+        for polygon in polygons
+    ]
+    timers = [ClockBasedTimer() for _ in zones]
+
+    for frame in frames_generator:
+        fps_monitor.tick()
+        fps = fps_monitor.fps
+
+        results = model.infer(frame, confidence=confidence, iou_threshold=iou)[0]
+        detections = sv.Detections.from_inference(results)
+        detections = detections[find_in_list(detections.class_id, classes)]
+        detections = tracker.update_with_detections(detections)
+
+        annotated_frame = frame.copy()
+        annotated_frame = sv.draw_text(
+            scene=annotated_frame,
+            text=f"{fps:.1f}",
+            text_anchor=sv.Point(40, 30),
+            background_color=sv.Color.from_hex("#A351FB"),
+            text_color=sv.Color.from_hex("#000000"),
+        )
+
+        for idx, zone in enumerate(zones):
+            annotated_frame = sv.draw_polygon(
+                scene=annotated_frame, polygon=zone.polygon, color=COLORS.by_idx(idx)
+            )
+
+            detections_in_zone = detections[zone.trigger(detections)]
+            time_in_zone = timers[idx].tick(detections_in_zone)
+            custom_color_lookup = np.full(detections_in_zone.class_id.shape, idx)
+
+            annotated_frame = COLOR_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                custom_color_lookup=custom_color_lookup,
+            )
+            labels = [
+                f"#{tracker_id} {int(time // 60):02d}:{int(time % 60):02d}"
+                for tracker_id, time in zip(detections_in_zone.tracker_id, time_in_zone)
+            ]
+            annotated_frame = LABEL_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                labels=labels,
+                custom_color_lookup=custom_color_lookup,
+            )
+
+        cv2.imshow("Processed Video", annotated_frame)
+        if cv2.waitKey(1) & 0xFF == ord("q"):
+            break
+    cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Calculating detections dwell time in zones, using RTSP stream."
+    )
+    parser.add_argument(
+        "--zone_configuration_path",
+        type=str,
+        required=True,
+        help="Path to the zone configuration JSON file.",
+    )
+    parser.add_argument(
+        "--rtsp_url",
+        type=str,
+        required=True,
+        help="Complete RTSP URL for the video stream.",
+    )
+    parser.add_argument(
+        "--model_id", type=str, default="yolov8s-640", help="Roboflow model ID."
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        type=float,
+        default=0.3,
+        help="Confidence level for detections (0 to 1). Default is 0.3.",
+    )
+    parser.add_argument(
+        "--iou_threshold",
+        default=0.7,
+        type=float,
+        help="IOU threshold for non-max suppression. Default is 0.7.",
+    )
+    parser.add_argument(
+        "--classes",
+        nargs="*",
+        type=int,
+        default=[],
+        help="List of class IDs to track. If empty, all classes are tracked.",
+    )
+    args = parser.parse_args()
+
+    main(
+        rtsp_url=args.rtsp_url,
+        zone_configuration_path=args.zone_configuration_path,
+        model_id=args.model_id,
+        confidence=args.confidence_threshold,
+        iou=args.iou_threshold,
+        classes=args.classes,
+    )

examples/time_in_zone/inference_stream_example.py

@@ -0,0 +1,153 @@
+import argparse
+from typing import List
+
+import cv2
+import numpy as np
+from inference import InferencePipeline
+from inference.core.interfaces.camera.entities import VideoFrame
+from utils.general import find_in_list, load_zones_config
+from utils.timers import ClockBasedTimer
+
+import supervision as sv
+
+COLORS = sv.ColorPalette.from_hex(["#E6194B", "#3CB44B", "#FFE119", "#3C76D1"])
+COLOR_ANNOTATOR = sv.ColorAnnotator(color=COLORS)
+LABEL_ANNOTATOR = sv.LabelAnnotator(
+    color=COLORS, text_color=sv.Color.from_hex("#000000")
+)
+
+
+class CustomSink:
+    def __init__(self, zone_configuration_path: str, classes: List[int]):
+        self.classes = classes
+        self.tracker = sv.ByteTrack(minimum_matching_threshold=0.5)
+        self.fps_monitor = sv.FPSMonitor()
+        self.polygons = load_zones_config(file_path=zone_configuration_path)
+        self.timers = [ClockBasedTimer() for _ in self.polygons]
+        self.zones = [
+            sv.PolygonZone(
+                polygon=polygon,
+                triggering_anchors=(sv.Position.CENTER,),
+            )
+            for polygon in self.polygons
+        ]
+
+    def on_prediction(self, result: dict, frame: VideoFrame) -> None:
+        self.fps_monitor.tick()
+        fps = self.fps_monitor.fps
+
+        detections = sv.Detections.from_inference(result)
+        detections = detections[find_in_list(detections.class_id, self.classes)]
+        detections = self.tracker.update_with_detections(detections)
+
+        annotated_frame = frame.image.copy()
+        annotated_frame = sv.draw_text(
+            scene=annotated_frame,
+            text=f"{fps:.1f}",
+            text_anchor=sv.Point(40, 30),
+            background_color=sv.Color.from_hex("#A351FB"),
+            text_color=sv.Color.from_hex("#000000"),
+        )
+
+        for idx, zone in enumerate(self.zones):
+            annotated_frame = sv.draw_polygon(
+                scene=annotated_frame, polygon=zone.polygon, color=COLORS.by_idx(idx)
+            )
+
+            detections_in_zone = detections[zone.trigger(detections)]
+            time_in_zone = self.timers[idx].tick(detections_in_zone)
+            custom_color_lookup = np.full(detections_in_zone.class_id.shape, idx)
+
+            annotated_frame = COLOR_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                custom_color_lookup=custom_color_lookup,
+            )
+            labels = [
+                f"#{tracker_id} {int(time // 60):02d}:{int(time % 60):02d}"
+                for tracker_id, time in zip(detections_in_zone.tracker_id, time_in_zone)
+            ]
+            annotated_frame = LABEL_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                labels=labels,
+                custom_color_lookup=custom_color_lookup,
+            )
+        cv2.imshow("Processed Video", annotated_frame)
+        cv2.waitKey(1)
+
+
+def main(
+    rtsp_url: str,
+    zone_configuration_path: str,
+    model_id: str,
+    confidence: float,
+    iou: float,
+    classes: List[int],
+) -> None:
+    sink = CustomSink(zone_configuration_path=zone_configuration_path, classes=classes)
+
+    pipeline = InferencePipeline.init(
+        model_id=model_id,
+        video_reference=rtsp_url,
+        on_prediction=sink.on_prediction,
+        confidence=confidence,
+        iou_threshold=iou,
+    )
+
+    pipeline.start()
+
+    try:
+        pipeline.join()
+    except KeyboardInterrupt:
+        pipeline.terminate()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Calculating detections dwell time in zones, using RTSP stream."
+    )
+    parser.add_argument(
+        "--zone_configuration_path",
+        type=str,
+        required=True,
+        help="Path to the zone configuration JSON file.",
+    )
+    parser.add_argument(
+        "--rtsp_url",
+        type=str,
+        required=True,
+        help="Complete RTSP URL for the video stream.",
+    )
+    parser.add_argument(
+        "--model_id", type=str, default="yolov8s-640", help="Roboflow model ID."
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        type=float,
+        default=0.3,
+        help="Confidence level for detections (0 to 1). Default is 0.3.",
+    )
+    parser.add_argument(
+        "--iou_threshold",
+        default=0.7,
+        type=float,
+        help="IOU threshold for non-max suppression. Default is 0.7.",
+    )
+    parser.add_argument(
+        "--classes",
+        nargs="*",
+        type=int,
+        default=[],
+        help="List of class IDs to track. If empty, all classes are tracked.",
+    )
+    args = parser.parse_args()
+
+    main(
+        rtsp_url=args.rtsp_url,
+        zone_configuration_path=args.zone_configuration_path,
+        model_id=args.model_id,
+        confidence=args.confidence_threshold,
+        iou=args.iou_threshold,
+        classes=args.classes,
+    )

examples/time_in_zone/requirements.txt

@@ -0,0 +1,5 @@
+opencv-python
+supervision>=0.20.0
+ultralytics
+inference==0.9.17
+pytube

examples/time_in_zone/scripts/download_from_youtube.py

@@ -0,0 +1,46 @@
+import argparse
+import os
+from typing import Optional
+
+from pytube import YouTube
+
+
+def main(url: str, output_path: Optional[str], file_name: Optional[str]) -> None:
+    yt = YouTube(url)
+    stream = yt.streams.get_highest_resolution()
+
+    if not os.path.exists(output_path):
+        os.makedirs(output_path)
+
+    stream.download(output_path=output_path, filename=file_name)
+    final_name = file_name if file_name else yt.title
+    final_path = output_path if output_path else "current directory"
+    print(f"Download completed! Video saved as '{final_name}' in '{final_path}'.")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Download a specific YouTube video by providing its URL."
+    )
+    parser.add_argument(
+        "--url",
+        type=str,
+        required=True,
+        help="The full URL of the YouTube video you wish to download.",
+    )
+    parser.add_argument(
+        "--output_path",
+        type=str,
+        default="data/source",
+        required=False,
+        help="Optional. Specifies the directory where the video will be saved.",
+    )
+    parser.add_argument(
+        "--file_name",
+        type=str,
+        default="video.mp4",
+        required=False,
+        help="Optional. Sets the name of the saved video file.",
+    )
+    args = parser.parse_args()
+    main(url=args.url, output_path=args.output_path, file_name=args.file_name)

examples/time_in_zone/scripts/draw_zones.py

@@ -0,0 +1,176 @@
+import argparse
+import json
+import os
+from typing import Any, Optional, Tuple
+
+import cv2
+import numpy as np
+
+import supervision as sv
+
+KEY_ENTER = 13
+KEY_NEWLINE = 10
+KEY_ESCAPE = 27
+KEY_QUIT = ord("q")
+KEY_SAVE = ord("s")
+
+THICKNESS = 2
+COLORS = sv.ColorPalette.DEFAULT
+WINDOW_NAME = "Draw Zones"
+POLYGONS = [[]]
+
+current_mouse_position: Optional[Tuple[int, int]] = None
+
+
+def resolve_source(source_path: str) -> Optional[np.ndarray]:
+    if not os.path.exists(source_path):
+        return None
+
+    image = cv2.imread(source_path)
+    if image is not None:
+        return image
+
+    frame_generator = sv.get_video_frames_generator(source_path=source_path)
+    frame = next(frame_generator)
+    return frame
+
+
+def mouse_event(event: int, x: int, y: int, flags: int, param: Any) -> None:
+    global current_mouse_position
+    if event == cv2.EVENT_MOUSEMOVE:
+        current_mouse_position = (x, y)
+    elif event == cv2.EVENT_LBUTTONDOWN:
+        POLYGONS[-1].append((x, y))
+
+
+def redraw(image: np.ndarray, original_image: np.ndarray) -> None:
+    global POLYGONS, current_mouse_position
+    image[:] = original_image.copy()
+    for idx, polygon in enumerate(POLYGONS):
+        color = (
+            COLORS.by_idx(idx).as_bgr()
+            if idx < len(POLYGONS) - 1
+            else sv.Color.WHITE.as_bgr()
+        )
+
+        if len(polygon) > 1:
+            for i in range(1, len(polygon)):
+                cv2.line(
+                    img=image,
+                    pt1=polygon[i - 1],
+                    pt2=polygon[i],
+                    color=color,
+                    thickness=THICKNESS,
+                )
+            if idx < len(POLYGONS) - 1:
+                cv2.line(
+                    img=image,
+                    pt1=polygon[-1],
+                    pt2=polygon[0],
+                    color=color,
+                    thickness=THICKNESS,
+                )
+        if idx == len(POLYGONS) - 1 and current_mouse_position is not None and polygon:
+            cv2.line(
+                img=image,
+                pt1=polygon[-1],
+                pt2=current_mouse_position,
+                color=color,
+                thickness=THICKNESS,
+            )
+    cv2.imshow(WINDOW_NAME, image)
+
+
+def close_and_finalize_polygon(image: np.ndarray, original_image: np.ndarray) -> None:
+    if len(POLYGONS[-1]) > 2:
+        cv2.line(
+            img=image,
+            pt1=POLYGONS[-1][-1],
+            pt2=POLYGONS[-1][0],
+            color=COLORS.by_idx(0).as_bgr(),
+            thickness=THICKNESS,
+        )
+    POLYGONS.append([])
+    image[:] = original_image.copy()
+    redraw_polygons(image)
+    cv2.imshow(WINDOW_NAME, image)
+
+
+def redraw_polygons(image: np.ndarray) -> None:
+    for idx, polygon in enumerate(POLYGONS[:-1]):
+        if len(polygon) > 1:
+            color = COLORS.by_idx(idx).as_bgr()
+            for i in range(len(polygon) - 1):
+                cv2.line(
+                    img=image,
+                    pt1=polygon[i],
+                    pt2=polygon[i + 1],
+                    color=color,
+                    thickness=THICKNESS,
+                )
+            cv2.line(
+                img=image,
+                pt1=polygon[-1],
+                pt2=polygon[0],
+                color=color,
+                thickness=THICKNESS,
+            )
+
+
+def save_polygons_to_json(polygons, target_path):
+    data_to_save = polygons if polygons[-1] else polygons[:-1]
+    with open(target_path, "w") as f:
+        json.dump(data_to_save, f)
+
+
+def main(source_path: str, zone_configuration_path: str) -> None:
+    global current_mouse_position
+    original_image = resolve_source(source_path=source_path)
+    if original_image is None:
+        print("Failed to load source image.")
+        return
+
+    image = original_image.copy()
+    cv2.imshow(WINDOW_NAME, image)
+    cv2.setMouseCallback(WINDOW_NAME, mouse_event, image)
+
+    while True:
+        key = cv2.waitKey(1) & 0xFF
+        if key == KEY_ENTER or key == KEY_NEWLINE:
+            close_and_finalize_polygon(image, original_image)
+        elif key == KEY_ESCAPE:
+            POLYGONS[-1] = []
+            current_mouse_position = None
+        elif key == KEY_SAVE:
+            save_polygons_to_json(POLYGONS, zone_configuration_path)
+            print(f"Polygons saved to {zone_configuration_path}")
+            break
+        redraw(image, original_image)
+        if key == KEY_QUIT:
+            break
+
+    cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Interactively draw polygons on images or video frames and save "
+        "the annotations."
+    )
+    parser.add_argument(
+        "--source_path",
+        type=str,
+        required=True,
+        help="Path to the source image or video file for drawing polygons.",
+    )
+    parser.add_argument(
+        "--zone_configuration_path",
+        type=str,
+        required=True,
+        help="Path where the polygon annotations will be saved as a JSON file.",
+    )
+    arguments = parser.parse_args()
+    main(
+        source_path=arguments.source_path,
+        zone_configuration_path=arguments.zone_configuration_path,
+    )

examples/time_in_zone/scripts/stream_from_file.py

@@ -0,0 +1,104 @@
+import argparse
+import os
+import subprocess
+import tempfile
+from glob import glob
+from threading import Thread
+
+import yaml
+
+SERVER_CONFIG = {"protocols": ["tcp"], "paths": {"all": {"source": "publisher"}}}
+BASE_STREAM_URL = "rtsp://localhost:8554/live"
+
+
+def main(video_directory: str, number_of_streams: int) -> None:
+    video_files = find_video_files_in_directory(video_directory, number_of_streams)
+    try:
+        with tempfile.TemporaryDirectory() as temporary_directory:
+            config_file_path = create_server_config_file(temporary_directory)
+            run_rtsp_server(config_path=config_file_path)
+            stream_videos(video_files)
+    finally:
+        stop_rtsp_server()
+
+
+def find_video_files_in_directory(directory: str, limit: int) -> list:
+    video_formats = ["*.mp4", "*.webm"]
+    video_paths = []
+    for video_format in video_formats:
+        video_paths.extend(glob(os.path.join(directory, video_format)))
+    return video_paths[:limit]
+
+
+def create_server_config_file(directory: str) -> str:
+    config_path = os.path.join(directory, "rtsp-simple-server.yml")
+    with open(config_path, "w") as config_file:
+        yaml.dump(SERVER_CONFIG, config_file)
+    return config_path
+
+
+def run_rtsp_server(config_path: str) -> None:
+    command = (
+        "docker run --rm --name rtsp_server -d -v "
+        f"{config_path}:/rtsp-simple-server.yml -p 8554:8554 "
+        "aler9/rtsp-simple-server:v1.3.0"
+    )
+    if run_command(command.split()) != 0:
+        raise RuntimeError("Could not start the RTSP server!")
+
+
+def stop_rtsp_server() -> None:
+    run_command("docker kill rtsp_server".split())
+
+
+def stream_videos(video_files: list) -> None:
+    threads = []
+    for index, video_file in enumerate(video_files):
+        stream_url = f"{BASE_STREAM_URL}{index}.stream"
+        print(f"Streaming {video_file} under {stream_url}")
+        thread = stream_video_to_url(video_file, stream_url)
+        threads.append(thread)
+    for thread in threads:
+        thread.join()
+
+
+def stream_video_to_url(video_path: str, stream_url: str) -> Thread:
+    command = (
+        f"ffmpeg -re -stream_loop -1 -i {video_path} "
+        f"-f rtsp -rtsp_transport tcp {stream_url}"
+    )
+    return run_command_in_thread(command.split())
+
+
+def run_command_in_thread(command: list) -> Thread:
+    thread = Thread(target=run_command, args=(command,))
+    thread.start()
+    return thread
+
+
+def run_command(command: list) -> int:
+    process = subprocess.run(command)
+    return process.returncode
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Script to stream videos using RTSP protocol."
+    )
+    parser.add_argument(
+        "--video_directory",
+        type=str,
+        required=True,
+        help="Directory containing video files to stream.",
+    )
+    parser.add_argument(
+        "--number_of_streams",
+        type=int,
+        default=6,
+        help="Number of video files to stream.",
+    )
+    arguments = parser.parse_args()
+    main(
+        video_directory=arguments.video_directory,
+        number_of_streams=arguments.number_of_streams,
+    )

examples/time_in_zone/ultralytics_file_example.py

@@ -0,0 +1,140 @@
+import argparse
+from typing import List
+
+import cv2
+import numpy as np
+from ultralytics import YOLO
+from utils.general import find_in_list, load_zones_config
+from utils.timers import FPSBasedTimer
+
+import supervision as sv
+
+COLORS = sv.ColorPalette.from_hex(["#E6194B", "#3CB44B", "#FFE119", "#3C76D1"])
+COLOR_ANNOTATOR = sv.ColorAnnotator(color=COLORS)
+LABEL_ANNOTATOR = sv.LabelAnnotator(
+    color=COLORS, text_color=sv.Color.from_hex("#000000")
+)
+
+
+def main(
+    source_video_path: str,
+    zone_configuration_path: str,
+    weights: str,
+    device: str,
+    confidence: float,
+    iou: float,
+    classes: List[int],
+) -> None:
+    model = YOLO(weights)
+    tracker = sv.ByteTrack(minimum_matching_threshold=0.5)
+    video_info = sv.VideoInfo.from_video_path(video_path=source_video_path)
+    frames_generator = sv.get_video_frames_generator(source_video_path)
+
+    polygons = load_zones_config(file_path=zone_configuration_path)
+    zones = [
+        sv.PolygonZone(
+            polygon=polygon,
+            triggering_anchors=(sv.Position.CENTER,),
+        )
+        for polygon in polygons
+    ]
+    timers = [FPSBasedTimer(video_info.fps) for _ in zones]
+
+    for frame in frames_generator:
+        results = model(frame, verbose=False, device=device, conf=confidence)[0]
+        detections = sv.Detections.from_ultralytics(results)
+        detections = detections[find_in_list(detections.class_id, classes)]
+        detections = detections.with_nms(threshold=iou)
+        detections = tracker.update_with_detections(detections)
+
+        annotated_frame = frame.copy()
+
+        for idx, zone in enumerate(zones):
+            annotated_frame = sv.draw_polygon(
+                scene=annotated_frame, polygon=zone.polygon, color=COLORS.by_idx(idx)
+            )
+
+            detections_in_zone = detections[zone.trigger(detections)]
+            time_in_zone = timers[idx].tick(detections_in_zone)
+            custom_color_lookup = np.full(detections_in_zone.class_id.shape, idx)
+
+            annotated_frame = COLOR_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                custom_color_lookup=custom_color_lookup,
+            )
+            labels = [
+                f"#{tracker_id} {int(time // 60):02d}:{int(time % 60):02d}"
+                for tracker_id, time in zip(detections_in_zone.tracker_id, time_in_zone)
+            ]
+            annotated_frame = LABEL_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                labels=labels,
+                custom_color_lookup=custom_color_lookup,
+            )
+
+        cv2.imshow("Processed Video", annotated_frame)
+        if cv2.waitKey(1) & 0xFF == ord("q"):
+            break
+    cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Calculating detections dwell time in zones, using video file."
+    )
+    parser.add_argument(
+        "--zone_configuration_path",
+        type=str,
+        required=True,
+        help="Path to the zone configuration JSON file.",
+    )
+    parser.add_argument(
+        "--source_video_path",
+        type=str,
+        required=True,
+        help="Path to the source video file.",
+    )
+    parser.add_argument(
+        "--weights",
+        type=str,
+        default="yolov8s.pt",
+        help="Path to the model weights file. Default is 'yolov8s.pt'.",
+    )
+    parser.add_argument(
+        "--device",
+        type=str,
+        default="cpu",
+        help="Computation device ('cpu', 'mps' or 'cuda'). Default is 'cpu'.",
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        type=float,
+        default=0.3,
+        help="Confidence level for detections (0 to 1). Default is 0.3.",
+    )
+    parser.add_argument(
+        "--iou_threshold",
+        default=0.7,
+        type=float,
+        help="IOU threshold for non-max suppression. Default is 0.7.",
+    )
+    parser.add_argument(
+        "--classes",
+        nargs="*",
+        type=int,
+        default=[],
+        help="List of class IDs to track. If empty, all classes are tracked.",
+    )
+    args = parser.parse_args()
+
+    main(
+        source_video_path=args.source_video_path,
+        zone_configuration_path=args.zone_configuration_path,
+        weights=args.weights,
+        device=args.device,
+        confidence=args.confidence_threshold,
+        iou=args.iou_threshold,
+        classes=args.classes,
+    )

examples/time_in_zone/ultralytics_naive_stream_example.py

@@ -0,0 +1,150 @@
+import argparse
+from typing import List
+
+import cv2
+import numpy as np
+from ultralytics import YOLO
+from utils.general import find_in_list, get_stream_frames_generator, load_zones_config
+from utils.timers import ClockBasedTimer
+
+import supervision as sv
+
+COLORS = sv.ColorPalette.from_hex(["#E6194B", "#3CB44B", "#FFE119", "#3C76D1"])
+COLOR_ANNOTATOR = sv.ColorAnnotator(color=COLORS)
+LABEL_ANNOTATOR = sv.LabelAnnotator(
+    color=COLORS, text_color=sv.Color.from_hex("#000000")
+)
+
+
+def main(
+    rtsp_url: str,
+    zone_configuration_path: str,
+    weights: str,
+    device: str,
+    confidence: float,
+    iou: float,
+    classes: List[int],
+) -> None:
+    model = YOLO(weights)
+    tracker = sv.ByteTrack(minimum_matching_threshold=0.5)
+    frames_generator = get_stream_frames_generator(rtsp_url=rtsp_url)
+    fps_monitor = sv.FPSMonitor()
+
+    polygons = load_zones_config(file_path=zone_configuration_path)
+    zones = [
+        sv.PolygonZone(
+            polygon=polygon,
+            triggering_anchors=(sv.Position.CENTER,),
+        )
+        for polygon in polygons
+    ]
+    timers = [ClockBasedTimer() for _ in zones]
+
+    for frame in frames_generator:
+        fps_monitor.tick()
+        fps = fps_monitor.fps
+
+        results = model(frame, verbose=False, device=device, conf=confidence)[0]
+        detections = sv.Detections.from_ultralytics(results)
+        detections = detections[find_in_list(detections.class_id, classes)]
+        detections = detections.with_nms(threshold=iou)
+        detections = tracker.update_with_detections(detections)
+
+        annotated_frame = frame.copy()
+        annotated_frame = sv.draw_text(
+            scene=annotated_frame,
+            text=f"{fps:.1f}",
+            text_anchor=sv.Point(40, 30),
+            background_color=sv.Color.from_hex("#A351FB"),
+            text_color=sv.Color.from_hex("#000000"),
+        )
+
+        for idx, zone in enumerate(zones):
+            annotated_frame = sv.draw_polygon(
+                scene=annotated_frame, polygon=zone.polygon, color=COLORS.by_idx(idx)
+            )
+
+            detections_in_zone = detections[zone.trigger(detections)]
+            time_in_zone = timers[idx].tick(detections_in_zone)
+            custom_color_lookup = np.full(detections_in_zone.class_id.shape, idx)
+
+            annotated_frame = COLOR_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                custom_color_lookup=custom_color_lookup,
+            )
+            labels = [
+                f"#{tracker_id} {int(time // 60):02d}:{int(time % 60):02d}"
+                for tracker_id, time in zip(detections_in_zone.tracker_id, time_in_zone)
+            ]
+            annotated_frame = LABEL_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                labels=labels,
+                custom_color_lookup=custom_color_lookup,
+            )
+
+        cv2.imshow("Processed Video", annotated_frame)
+        if cv2.waitKey(1) & 0xFF == ord("q"):
+            break
+    cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Calculating detections dwell time in zones, using RTSP stream."
+    )
+    parser.add_argument(
+        "--zone_configuration_path",
+        type=str,
+        required=True,
+        help="Path to the zone configuration JSON file.",
+    )
+    parser.add_argument(
+        "--rtsp_url",
+        type=str,
+        required=True,
+        help="Complete RTSP URL for the video stream.",
+    )
+    parser.add_argument(
+        "--weights",
+        type=str,
+        default="yolov8s.pt",
+        help="Path to the model weights file. Default is 'yolov8s.pt'.",
+    )
+    parser.add_argument(
+        "--device",
+        type=str,
+        default="cpu",
+        help="Computation device ('cpu', 'mps' or 'cuda'). Default is 'cpu'.",
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        type=float,
+        default=0.3,
+        help="Confidence level for detections (0 to 1). Default is 0.3.",
+    )
+    parser.add_argument(
+        "--iou_threshold",
+        default=0.7,
+        type=float,
+        help="IOU threshold for non-max suppression. Default is 0.7.",
+    )
+    parser.add_argument(
+        "--classes",
+        nargs="*",
+        type=int,
+        default=[],
+        help="List of class IDs to track. If empty, all classes are tracked.",
+    )
+    args = parser.parse_args()
+
+    main(
+        rtsp_url=args.rtsp_url,
+        zone_configuration_path=args.zone_configuration_path,
+        weights=args.weights,
+        device=args.device,
+        confidence=args.confidence_threshold,
+        iou=args.iou_threshold,
+        classes=args.classes,
+    )

examples/time_in_zone/ultralytics_stream_example.py

@@ -0,0 +1,168 @@
+import argparse
+from typing import List
+
+import cv2
+import numpy as np
+from inference import InferencePipeline
+from inference.core.interfaces.camera.entities import VideoFrame
+from ultralytics import YOLO
+from utils.general import find_in_list, load_zones_config
+from utils.timers import ClockBasedTimer
+
+import supervision as sv
+
+COLORS = sv.ColorPalette.from_hex(["#E6194B", "#3CB44B", "#FFE119", "#3C76D1"])
+COLOR_ANNOTATOR = sv.ColorAnnotator(color=COLORS)
+LABEL_ANNOTATOR = sv.LabelAnnotator(
+    color=COLORS, text_color=sv.Color.from_hex("#000000")
+)
+
+
+class CustomSink:
+    def __init__(self, zone_configuration_path: str, classes: List[int]):
+        self.classes = classes
+        self.tracker = sv.ByteTrack(minimum_matching_threshold=0.8)
+        self.fps_monitor = sv.FPSMonitor()
+        self.polygons = load_zones_config(file_path=zone_configuration_path)
+        self.timers = [ClockBasedTimer() for _ in self.polygons]
+        self.zones = [
+            sv.PolygonZone(
+                polygon=polygon,
+                triggering_anchors=(sv.Position.CENTER,),
+            )
+            for polygon in self.polygons
+        ]
+
+    def on_prediction(self, detections: sv.Detections, frame: VideoFrame) -> None:
+        self.fps_monitor.tick()
+        fps = self.fps_monitor.fps
+
+        detections = detections[find_in_list(detections.class_id, self.classes)]
+        detections = self.tracker.update_with_detections(detections)
+
+        annotated_frame = frame.image.copy()
+        annotated_frame = sv.draw_text(
+            scene=annotated_frame,
+            text=f"{fps:.1f}",
+            text_anchor=sv.Point(40, 30),
+            background_color=sv.Color.from_hex("#A351FB"),
+            text_color=sv.Color.from_hex("#000000"),
+        )
+
+        for idx, zone in enumerate(self.zones):
+            annotated_frame = sv.draw_polygon(
+                scene=annotated_frame, polygon=zone.polygon, color=COLORS.by_idx(idx)
+            )
+
+            detections_in_zone = detections[zone.trigger(detections)]
+            time_in_zone = self.timers[idx].tick(detections_in_zone)
+            custom_color_lookup = np.full(detections_in_zone.class_id.shape, idx)
+
+            annotated_frame = COLOR_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                custom_color_lookup=custom_color_lookup,
+            )
+            labels = [
+                f"#{tracker_id} {int(time // 60):02d}:{int(time % 60):02d}"
+                for tracker_id, time in zip(detections_in_zone.tracker_id, time_in_zone)
+            ]
+            annotated_frame = LABEL_ANNOTATOR.annotate(
+                scene=annotated_frame,
+                detections=detections_in_zone,
+                labels=labels,
+                custom_color_lookup=custom_color_lookup,
+            )
+        cv2.imshow("Processed Video", annotated_frame)
+        cv2.waitKey(1)
+
+
+def main(
+    rtsp_url: str,
+    zone_configuration_path: str,
+    weights: str,
+    device: str,
+    confidence: float,
+    iou: float,
+    classes: List[int],
+) -> None:
+    model = YOLO(weights)
+
+    def inference_callback(frame: VideoFrame) -> sv.Detections:
+        results = model(frame.image, verbose=False, conf=confidence, device=device)[0]
+        return sv.Detections.from_ultralytics(results).with_nms(threshold=iou)
+
+    sink = CustomSink(zone_configuration_path=zone_configuration_path, classes=classes)
+
+    pipeline = InferencePipeline.init_with_custom_logic(
+        video_reference=rtsp_url,
+        on_video_frame=inference_callback,
+        on_prediction=sink.on_prediction,
+    )
+
+    pipeline.start()
+
+    try:
+        pipeline.join()
+    except KeyboardInterrupt:
+        pipeline.terminate()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Calculating detections dwell time in zones, using RTSP stream."
+    )
+    parser.add_argument(
+        "--zone_configuration_path",
+        type=str,
+        required=True,
+        help="Path to the zone configuration JSON file.",
+    )
+    parser.add_argument(
+        "--rtsp_url",
+        type=str,
+        required=True,
+        help="Complete RTSP URL for the video stream.",
+    )
+    parser.add_argument(
+        "--weights",
+        type=str,
+        default="yolov8s.pt",
+        help="Path to the model weights file. Default is 'yolov8s.pt'.",
+    )
+    parser.add_argument(
+        "--device",
+        type=str,
+        default="cpu",
+        help="Computation device ('cpu', 'mps' or 'cuda'). Default is 'cpu'.",
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        type=float,
+        default=0.3,
+        help="Confidence level for detections (0 to 1). Default is 0.3.",
+    )
+    parser.add_argument(
+        "--iou_threshold",
+        default=0.7,
+        type=float,
+        help="IOU threshold for non-max suppression. Default is 0.7.",
+    )
+    parser.add_argument(
+        "--classes",
+        nargs="*",
+        type=int,
+        default=[],
+        help="List of class IDs to track. If empty, all classes are tracked.",
+    )
+    args = parser.parse_args()
+
+    main(
+        rtsp_url=args.rtsp_url,
+        zone_configuration_path=args.zone_configuration_path,
+        weights=args.weights,
+        device=args.device,
+        confidence=args.confidence_threshold,
+        iou=args.iou_threshold,
+        classes=args.classes,
+    )

examples/time_in_zone/utils/general.py

@@ -0,0 +1,66 @@
+import json
+from typing import Generator, List
+
+import cv2
+import numpy as np
+
+
+def load_zones_config(file_path: str) -> List[np.ndarray]:
+    """
+    Load polygon zone configurations from a JSON file.
+
+    This function reads a JSON file which contains polygon coordinates, and
+    converts them into a list of NumPy arrays. Each polygon is represented as
+    a NumPy array of coordinates.
+
+    Args:
+        file_path (str): The path to the JSON configuration file.
+
+    Returns:
+        List[np.ndarray]: A list of polygons, each represented as a NumPy array.
+    """
+    with open(file_path, "r") as file:
+        data = json.load(file)
+        return [np.array(polygon, np.int32) for polygon in data]
+
+
+def find_in_list(array: np.ndarray, search_list: List[int]) -> np.ndarray:
+    """Determines if elements of a numpy array are present in a list.
+
+    Args:
+        array (np.ndarray): The numpy array of integers to check.
+        search_list (List[int]): The list of integers to search within.
+
+    Returns:
+        np.ndarray: A numpy array of booleans, where each boolean indicates whether
+        the corresponding element in `array` is found in `search_list`.
+    """
+    if not search_list:
+        return np.ones(array.shape, dtype=bool)
+    else:
+        return np.isin(array, search_list)
+
+
+def get_stream_frames_generator(rtsp_url: str) -> Generator[np.ndarray, None, None]:
+    """
+    Generator function to yield frames from an RTSP stream.
+
+    Args:
+        rtsp_url (str): URL of the RTSP video stream.
+
+    Yields:
+        np.ndarray: The next frame from the video stream.
+    """
+    cap = cv2.VideoCapture(rtsp_url)
+    if not cap.isOpened():
+        raise Exception("Error: Could not open video stream.")
+
+    try:
+        while True:
+            ret, frame = cap.read()
+            if not ret:
+                print("End of stream or error reading frame.")
+                break
+            yield frame
+    finally:
+        cap.release()

examples/time_in_zone/utils/timers.py

@@ -0,0 +1,88 @@
+from datetime import datetime
+from typing import Dict
+
+import numpy as np
+
+import supervision as sv
+
+
+class FPSBasedTimer:
+    """
+    A timer that calculates the duration each object has been detected based on frames
+    per second (FPS).
+
+    Attributes:
+        fps (int): The frame rate of the video stream, used to calculate time durations.
+        frame_id (int): The current frame number in the sequence.
+        tracker_id2frame_id (Dict[int, int]): Maps each tracker's ID to the frame number
+            at which it was first detected.
+    """
+
+    def __init__(self, fps: int = 30) -> None:
+        """Initializes the FPSBasedTimer with the specified frames per second rate.
+
+        Args:
+            fps (int, optional): The frame rate of the video stream. Defaults to 30.
+        """
+        self.fps = fps
+        self.frame_id = 0
+        self.tracker_id2frame_id: Dict[int, int] = {}
+
+    def tick(self, detections: sv.Detections) -> np.ndarray:
+        """Processes the current frame, updating time durations for each tracker.
+
+        Args:
+            detections: The detections for the current frame, including tracker IDs.
+
+        Returns:
+            np.ndarray: Time durations (in seconds) for each detected tracker, since
+                their first detection.
+        """
+        self.frame_id += 1
+        times = []
+
+        for tracker_id in detections.tracker_id:
+            self.tracker_id2frame_id.setdefault(tracker_id, self.frame_id)
+
+            start_frame_id = self.tracker_id2frame_id[tracker_id]
+            time_duration = (self.frame_id - start_frame_id) / self.fps
+            times.append(time_duration)
+
+        return np.array(times)
+
+
+class ClockBasedTimer:
+    """
+    A timer that calculates the duration each object has been detected based on the
+    system clock.
+
+    Attributes:
+        tracker_id2start_time (Dict[int, datetime]): Maps each tracker's ID to the
+            datetime when it was first detected.
+    """
+
+    def __init__(self) -> None:
+        """Initializes the ClockBasedTimer."""
+        self.tracker_id2start_time: Dict[int, datetime] = {}
+
+    def tick(self, detections: sv.Detections) -> np.ndarray:
+        """Processes the current frame, updating time durations for each tracker.
+
+        Args:
+            detections: The detections for the current frame, including tracker IDs.
+
+        Returns:
+            np.ndarray: Time durations (in seconds) for each detected tracker, since
+                their first detection.
+        """
+        current_time = datetime.now()
+        times = []
+
+        for tracker_id in detections.tracker_id:
+            self.tracker_id2start_time.setdefault(tracker_id, current_time)
+
+            start_time = self.tracker_id2start_time[tracker_id]
+            time_duration = (current_time - start_time).total_seconds()
+            times.append(time_duration)
+
+        return np.array(times)

examples/tracking/requirements.txt

@@ -1,4 +1,4 @@
-inference
-supervision
+inference==0.9.17
+supervision==0.19.0
 tqdm
 ultralytics

examples/traffic_analysis/inference_example.py

@@ -1,6 +1,6 @@
 import argparse
 import os
-from typing import Dict, List, Set, Tuple
+from typing import Dict, Iterable, List, Set
 
 import cv2
 import numpy as np
@@ -9,7 +9,8 @@ from tqdm import tqdm
 
 import supervision as sv
 
-COLORS = sv.ColorPalette.default()
+COLORS = sv.ColorPalette.from_hex(["#E6194B", "#3CB44B", "#FFE119", "#3C76D1"])
+
 
 ZONE_IN_POLYGONS = [
     np.array([[592, 282], [900, 282], [900, 82], [592, 82]]),
@@ -59,14 +60,12 @@ class DetectionsManager:
 
 def initiate_polygon_zones(
     polygons: List[np.ndarray],
-    frame_resolution_wh: Tuple[int, int],
-    triggering_position: sv.Position = sv.Position.CENTER,
+    triggering_anchors: Iterable[sv.Position] = [sv.Position.CENTER],
 ) -> List[sv.PolygonZone]:
     return [
         sv.PolygonZone(
             polygon=polygon,
-            frame_resolution_wh=frame_resolution_wh,
-            triggering_position=triggering_position,
+            triggering_anchors=triggering_anchors,
         )
         for polygon in polygons
     ]
@@ -91,14 +90,13 @@ class VideoProcessor:
         self.tracker = sv.ByteTrack()
 
         self.video_info = sv.VideoInfo.from_video_path(source_video_path)
-        self.zones_in = initiate_polygon_zones(
-            ZONE_IN_POLYGONS, self.video_info.resolution_wh, sv.Position.CENTER
-        )
-        self.zones_out = initiate_polygon_zones(
-            ZONE_OUT_POLYGONS, self.video_info.resolution_wh, sv.Position.CENTER
-        )
+        self.zones_in = initiate_polygon_zones(ZONE_IN_POLYGONS, [sv.Position.CENTER])
+        self.zones_out = initiate_polygon_zones(ZONE_OUT_POLYGONS, [sv.Position.CENTER])
 
-        self.box_annotator = sv.BoxAnnotator(color=COLORS)
+        self.bounding_box_annotator = sv.BoundingBoxAnnotator(color=COLORS)
+        self.label_annotator = sv.LabelAnnotator(
+            color=COLORS, text_color=sv.Color.BLACK
+        )
         self.trace_annotator = sv.TraceAnnotator(
             color=COLORS, position=sv.Position.CENTER, trace_length=100, thickness=2
         )
@@ -136,7 +134,10 @@ class VideoProcessor:
 
         labels = [f"#{tracker_id}" for tracker_id in detections.tracker_id]
         annotated_frame = self.trace_annotator.annotate(annotated_frame, detections)
-        annotated_frame = self.box_annotator.annotate(
+        annotated_frame = self.bounding_box_annotator.annotate(
+            annotated_frame, detections
+        )
+        annotated_frame = self.label_annotator.annotate(
             annotated_frame, detections, labels
         )
 
@@ -167,7 +168,7 @@ class VideoProcessor:
         detections_in_zones = []
         detections_out_zones = []
 
-        for i, (zone_in, zone_out) in enumerate(zip(self.zones_in, self.zones_out)):
+        for zone_in, zone_out in zip(self.zones_in, self.zones_out):
             detections_in_zone = detections[zone_in.trigger(detections=detections)]
             detections_in_zones.append(detections_in_zone)
             detections_out_zone = detections[zone_out.trigger(detections=detections)]

examples/traffic_analysis/requirements.txt

@@ -1,5 +1,5 @@
 gdown
-inference
-supervision
+inference==0.9.17
+supervision>=0.20.0
 tqdm
 ultralytics

examples/traffic_analysis/ultralytics_example.py

@@ -1,5 +1,5 @@
 import argparse
-from typing import Dict, List, Set, Tuple
+from typing import Dict, Iterable, List, Set
 
 import cv2
 import numpy as np
@@ -8,7 +8,7 @@ from ultralytics import YOLO
 
 import supervision as sv
 
-COLORS = sv.ColorPalette.default()
+COLORS = sv.ColorPalette.from_hex(["#E6194B", "#3CB44B", "#FFE119", "#3C76D1"])
 
 ZONE_IN_POLYGONS = [
     np.array([[592, 282], [900, 282], [900, 82], [592, 82]]),
@@ -58,14 +58,12 @@ class DetectionsManager:
 
 def initiate_polygon_zones(
     polygons: List[np.ndarray],
-    frame_resolution_wh: Tuple[int, int],
-    triggering_position: sv.Position = sv.Position.CENTER,
+    triggering_anchors: Iterable[sv.Position] = [sv.Position.CENTER],
 ) -> List[sv.PolygonZone]:
     return [
         sv.PolygonZone(
             polygon=polygon,
-            frame_resolution_wh=frame_resolution_wh,
-            triggering_position=triggering_position,
+            triggering_anchors=triggering_anchors,
         )
         for polygon in polygons
     ]
@@ -89,14 +87,13 @@ class VideoProcessor:
         self.tracker = sv.ByteTrack()
 
         self.video_info = sv.VideoInfo.from_video_path(source_video_path)
-        self.zones_in = initiate_polygon_zones(
-            ZONE_IN_POLYGONS, self.video_info.resolution_wh, sv.Position.CENTER
-        )
-        self.zones_out = initiate_polygon_zones(
-            ZONE_OUT_POLYGONS, self.video_info.resolution_wh, sv.Position.CENTER
-        )
+        self.zones_in = initiate_polygon_zones(ZONE_IN_POLYGONS, [sv.Position.CENTER])
+        self.zones_out = initiate_polygon_zones(ZONE_OUT_POLYGONS, [sv.Position.CENTER])
 
-        self.box_annotator = sv.BoxAnnotator(color=COLORS)
+        self.bounding_box_annotator = sv.BoundingBoxAnnotator(color=COLORS)
+        self.label_annotator = sv.LabelAnnotator(
+            color=COLORS, text_color=sv.Color.BLACK
+        )
         self.trace_annotator = sv.TraceAnnotator(
             color=COLORS, position=sv.Position.CENTER, trace_length=100, thickness=2
         )
@@ -134,7 +131,10 @@ class VideoProcessor:
 
         labels = [f"#{tracker_id}" for tracker_id in detections.tracker_id]
         annotated_frame = self.trace_annotator.annotate(annotated_frame, detections)
-        annotated_frame = self.box_annotator.annotate(
+        annotated_frame = self.bounding_box_annotator.annotate(
+            annotated_frame, detections
+        )
+        annotated_frame = self.label_annotator.annotate(
             annotated_frame, detections, labels
         )
 
@@ -165,7 +165,7 @@ class VideoProcessor:
         detections_in_zones = []
         detections_out_zones = []
 
-        for i, (zone_in, zone_out) in enumerate(zip(self.zones_in, self.zones_out)):
+        for zone_in, zone_out in zip(self.zones_in, self.zones_out):
             detections_in_zone = detections[zone_in.trigger(detections=detections)]
             detections_in_zones.append(detections_in_zone)
             detections_out_zone = detections[zone_out.trigger(detections=detections)]

mkdocs.yml

@@ -31,55 +31,75 @@ extra:
 
 extra_css:
   - stylesheets/extra.css
+  - stylesheets/cookbooks-card.css
+
 
 nav:
-  - Home: index.md
-  - How to:
+  - Supervision: index.md
+  - Learn:
       - Detect and Annotate: how_to/detect_and_annotate.md
-      - Track Objects: how_to/track_objects.md
+      - Save Detections: how_to/save_detections.md
       - Filter Detections: how_to/filter_detections.md
-  - API:
-    - Classifications:
-        - Core: classification/core.md
-    - Detections:
+      - Detect Small Objects: how_to/detect_small_objects.md
+      - Track Objects on Video: how_to/track_objects.md
+
+  - Reference - Code API:
+    - Detection and Segmentation:
         - Core: detection/core.md
+        - Annotators: detection/annotators.md
+        - Metrics: detection/metrics.md
+        - Double Detection Filter: detection/double_detection_filter.md
         - Utils: detection/utils.md
+    - Keypoint Detection:
+        - Core: keypoint/core.md
+        - Annotators: keypoint/annotators.md
+    - Classification:
+        - Core: classification/core.md
     - Tools:
         - Line Zone: detection/tools/line_zone.md
         - Polygon Zone: detection/tools/polygon_zone.md
         - Inference Slicer: detection/tools/inference_slicer.md
         - Detection Smoother: detection/tools/smoother.md
         - Save Detections: detection/tools/save_detections.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
-    - Geometry:
-        - Position: geometry/core.md
+    - Datasets:
+        - Core: datasets/core.md
+        - Utils: datasets/utils.md
     - Utils:
         - Video: utils/video.md
         - Image: utils/image.md
+        - Iterables: utils/iterables.md
         - Notebook: utils/notebook.md
         - File: utils/file.md
-  - Assets: assets.md
-  - Development:
+        - Draw: utils/draw.md
+        - Geometry: utils/geometry.md
+    - Assets: assets.md
+  - Cookbooks: cookbooks.md
+  - Contribute:
     - Contributing: contributing.md
     - Code of Conduct: code_of_conduct.md
-  - Changelog:
+    - License: license.md
+  - Release Notes:
         - Changelog: changelog.md
         - Deprecated: deprecated.md
-  - License: license.md
+
 
 
 theme:
   name: 'material'
+  icon:
+    edit: material/pencil
   logo: assets/supervision-lenny.png
   favicon: assets/supervision-lenny.png
   custom_dir: docs/theme
+  features:
+    - navigation.tracking
+    - content.code.copy
+    - content.action.edit
+    - content.tooltips
+    - content.code.annotate
+    - navigation.tabs
+
   palette:
     # Palette for light mode
     - scheme: default
@@ -94,15 +114,22 @@ theme:
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
+
+
   font:
     text: Roboto
     code: Roboto Mono
-  features:
-    - content.code.copy
-    - content.code.annotate
+    features:
+      - content.code.copy
+      - content.code.annotate
 
 plugins:
   - search
+  - mkdocs-jupyter:
+        kernel_name: python3
+        execute: false
+        include_source: True
+        include_requirejs: true
   - mkdocstrings:
       default_handler: python
       handlers:
@@ -118,9 +145,15 @@ plugins:
             show_symbol_type_heading: true
             show_symbol_type_toc: true
             show_category_heading: true
-          import:
-          - https://docs.python-requests.org/en/master/objects.inv
           domains: [std, py]
+  - git-committers:
+      repository: roboflow/supervision
+      branch: develop
+      token: !ENV ["GITHUB_TOKEN"]
+  - git-revision-date-localized:
+      enable_creation_date: true
+
+
 
 markdown_extensions:
   - admonition
@@ -137,7 +170,11 @@ markdown_extensions:
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.snippets:
       check_paths: true
+  - pymdownx.highlight:
+      anchor_linenums: true
 
 extra_javascript:
   - "https://widget.kapa.ai/kapa-widget.bundle.js"
-  - "javascript/init_kapa_widget.js"
+  - "javascripts/init_kapa_widget.js"
+  - "javascripts/cookbooks-card.js"
+  - "https://cdnjs.cloudflare.com/ajax/libs/dompurify/3.0.8/purify.min.js"

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "supervision"
-version = "0.19.0rc2"
+version = "0.21.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>"]
@@ -39,35 +39,42 @@ scipy = [
 ]
 matplotlib = ">=3.6.0"
 pyyaml = ">=5.3"
+defusedxml = "^0.7.1"
 opencv-python = { version = ">=4.5.5.64", optional = true }
 opencv-python-headless = ">=4.5.5.64"
-requests = { version = ">=2.26.0,<=2.31.0", optional = true }
-tqdm = { version = ">=4.62.3,<=4.66.1", optional = true }
-defusedxml = "^0.7.1"
-
-
+requests = { version = ">=2.26.0,<=2.32.3", optional = true }
+tqdm = { version = ">=4.62.3,<=4.66.4", optional = true }
+pillow = ">=9.4"
 
 [tool.poetry.extras]
 desktop = ["opencv-python"]
 assets = ["requests","tqdm"]
 
 [tool.poetry.group.dev.dependencies]
-twine = "^4.0.2"
+twine = ">=4.0.2,<6.0.0"
 pytest = ">=7.2.2,<9.0.0"
-wheel = ">=0.40,<0.43"
-notebook = ">=6.5.3,<8.0.0"
-build = ">=0.10,<1.1"
+wheel = ">=0.40,<0.44"
+build = ">=0.10,<1.3"
 ruff = ">=0.1.0"
-isort = "^5.12.0"
 mypy = "^1.4.1"
 pre-commit = "^3.3.3"
 tox = "^4.11.4"
+notebook = ">=6.5.3,<8.0.0"
+ipywidgets = "^8.1.1"
+jupytext = "^1.16.1"
+nbconvert = "^7.14.2"
 
 
 [tool.poetry.group.docs.dependencies]
 mkdocs-material = {extras = ["imaging"], version = "^9.5.5"}
-mkdocstrings = {extras = ["python"], version = ">=0.20,<0.25"}
+mkdocstrings = {extras = ["python"], version = ">=0.20,<0.26"}
 mike = "^2.0.0"
+# For Documentation Development use Python 3.10 or above
+# Use Latest mkdocs-jupyter min 0.24.6 for Jupyter Notebook Theme support
+mkdocs-jupyter = "^0.24.3"
+mkdocs-git-committers-plugin-2 = "^2.2.3"
+mkdocs-git-revision-date-localized-plugin = "^1.2.4"
+
 
 
 [tool.isort]
@@ -104,13 +111,6 @@ exclude = '''
 
 [tool.ruff]
 target-version = "py38"
-# Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default.
-select = ["E", "F"]
-ignore = []
-
-# Allow autofix for all enabled rules (when `--fix`) is provided.
-fixable = ["A", "B", "C", "D", "E", "F", "G", "I", "N", "Q", "S", "T", "W", "ANN", "ARG", "BLE", "COM", "DJ", "DTZ", "EM", "ERA", "EXE", "FBT", "ICN", "INP", "ISC", "NPY", "PD", "PGH", "PIE", "PL", "PT", "PTH", "PYI", "RET", "RSE", "RUF", "SIM", "SLF", "TCH", "TID", "TRY", "UP", "YTT"]
-unfixable = []
 
 # Exclude a variety of commonly ignored directories.
 exclude = [
@@ -140,33 +140,35 @@ exclude = [
     "docs",
 ]
 
-# Same as Black.
 line-length = 88
 indent-width = 4
 
+[tool.ruff.lint]
+# Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default.
+select = ["E", "F"]
+ignore = []
+# Allow autofix for all enabled rules (when `--fix`) is provided.
+fixable = ["A", "B", "C", "D", "E", "F", "G", "I", "N", "Q", "S", "T", "W", "ANN", "ARG", "BLE", "COM", "DJ", "DTZ", "EM", "ERA", "EXE", "FBT", "ICN", "INP", "ISC", "NPY", "PD", "PGH", "PIE", "PL", "PT", "PTH", "PYI", "RET", "RSE", "RUF", "SIM", "SLF", "TCH", "TID", "TRY", "UP", "YTT"]
+unfixable = []
 # Allow unused variables when underscore-prefixed.
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+pylint.max-args = 20
 
-[tool.ruff.flake8-quotes]
+[tool.ruff.lint.flake8-quotes]
 inline-quotes = "double"
 multiline-quotes = "double"
 docstring-quotes = "double"
 
-[tool.ruff.pydocstyle]
+[tool.ruff.lint.pydocstyle]
 convention = "google"
 
-[tool.ruff.per-file-ignores]
+[tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["E402","F401"]
-"supervision/assets/list.py" = ["E501"]
 
 [tool.ruff.lint.mccabe]
 # Flag errors (`C901`) whenever the complexity level exceeds 5.
 max-complexity = 20
 
-
-[tool.ruff.pylint]
-max-args = 20
-
 [tool.ruff.format]
 # Like Black, use double quotes for strings.
 quote-style = "double"

supervision/__init__.py

@@ -12,6 +12,7 @@ from supervision.annotators.core import (
     BoxCornerAnnotator,
     CircleAnnotator,
     ColorAnnotator,
+    CropAnnotator,
     DotAnnotator,
     EllipseAnnotator,
     HaloAnnotator,
@@ -22,6 +23,7 @@ from supervision.annotators.core import (
     PercentageBarAnnotator,
     PixelateAnnotator,
     PolygonAnnotator,
+    RichLabelAnnotator,
     RoundBoxAnnotator,
     TraceAnnotator,
     TriangleAnnotator,
@@ -33,29 +35,43 @@ from supervision.dataset.core import (
     ClassificationDataset,
     DetectionDataset,
 )
+from supervision.dataset.utils import mask_to_rle, rle_to_mask
 from supervision.detection.annotate import BoxAnnotator
 from supervision.detection.core import Detections
-from supervision.detection.line_counter import LineZone, LineZoneAnnotator
+from supervision.detection.line_zone import LineZone, LineZoneAnnotator
+from supervision.detection.lmm import LMM
+from supervision.detection.overlap_filter import (
+    OverlapFilter,
+    box_non_max_merge,
+    box_non_max_suppression,
+    mask_non_max_suppression,
+)
 from supervision.detection.tools.csv_sink import CSVSink
 from supervision.detection.tools.inference_slicer import InferenceSlicer
+from supervision.detection.tools.json_sink import JSONSink
 from supervision.detection.tools.polygon_zone import PolygonZone, PolygonZoneAnnotator
 from supervision.detection.tools.smoother import DetectionsSmoother
 from supervision.detection.utils import (
     box_iou_batch,
     calculate_masks_centroids,
+    clip_boxes,
+    contains_holes,
+    contains_multiple_segments,
     filter_polygons_by_area,
+    mask_iou_batch,
     mask_to_polygons,
     mask_to_xyxy,
     move_boxes,
-    non_max_suppression,
+    move_masks,
+    pad_boxes,
     polygon_to_mask,
     polygon_to_xyxy,
     scale_boxes,
 )
 from supervision.draw.color import Color, ColorPalette
 from supervision.draw.utils import (
-    calculate_dynamic_line_thickness,
-    calculate_dynamic_text_scale,
+    calculate_optimal_line_thickness,
+    calculate_optimal_text_scale,
     draw_filled_rectangle,
     draw_image,
     draw_line,
@@ -65,10 +81,25 @@ from supervision.draw.utils import (
 )
 from supervision.geometry.core import Point, Position, Rect
 from supervision.geometry.utils import get_polygon_center
+from supervision.keypoint.annotators import (
+    EdgeAnnotator,
+    VertexAnnotator,
+    VertexLabelAnnotator,
+)
+from supervision.keypoint.core import KeyPoints
 from supervision.metrics.detection import ConfusionMatrix, MeanAveragePrecision
 from supervision.tracker.byte_tracker.core import ByteTrack
+from supervision.utils.conversion import cv2_to_pillow, pillow_to_cv2
 from supervision.utils.file import list_files_with_extensions
-from supervision.utils.image import ImageSink, crop_image
+from supervision.utils.image import (
+    ImageSink,
+    create_tiles,
+    crop_image,
+    letterbox_image,
+    overlay_image,
+    resize_image,
+    scale_image,
+)
 from supervision.utils.notebook import plot_image, plot_images_grid
 from supervision.utils.video import (
     FPSMonitor,

supervision/annotators/base.py

@@ -1,11 +1,22 @@
 from abc import ABC, abstractmethod
+from typing import TypeVar
 
 import numpy as np
+from PIL import Image
 
 from supervision.detection.core import Detections
 
+ImageType = TypeVar("ImageType", np.ndarray, Image.Image)
+"""
+An image of type `np.ndarray` or `PIL.Image.Image`.
+
+Unlike a `Union`, ensures the type remains consistent. If a function
+takes an `ImageType` argument and returns an `ImageType`, when you
+pass an `np.ndarray`, you will get an `np.ndarray` back.
+"""
+
 
 class BaseAnnotator(ABC):
     @abstractmethod
-    def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
+    def annotate(self, scene: ImageType, detections: Detections) -> ImageType:
         pass

supervision/annotators/utils.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import Optional, Union
+from typing import Optional, Tuple, Union
 
 import numpy as np
 
@@ -34,14 +34,14 @@ def resolve_color_idx(
 ) -> int:
     if detection_idx >= len(detections):
         raise ValueError(
-            f"Detection index {detection_idx}"
+            f"Detection index {detection_idx} "
             f"is out of bounds for detections of length {len(detections)}"
         )
 
     if isinstance(color_lookup, np.ndarray):
         if len(color_lookup) != len(detections):
             raise ValueError(
-                f"Length of color lookup {len(color_lookup)}"
+                f"Length of color lookup {len(color_lookup)} "
                 f"does not match length of detections {len(detections)}"
             )
         return color_lookup[detection_idx]
@@ -50,19 +50,72 @@ def resolve_color_idx(
     elif color_lookup == ColorLookup.CLASS:
         if detections.class_id is None:
             raise ValueError(
-                "Could not resolve color by class because"
+                "Could not resolve color by class because "
                 "Detections do not have class_id"
             )
         return detections.class_id[detection_idx]
     elif color_lookup == ColorLookup.TRACK:
         if detections.tracker_id is None:
             raise ValueError(
-                "Could not resolve color by track because"
+                "Could not resolve color by track because "
                 "Detections do not have tracker_id"
             )
         return detections.tracker_id[detection_idx]
 
 
+def resolve_text_background_xyxy(
+    center_coordinates: Tuple[int, int],
+    text_wh: Tuple[int, int],
+    position: Position,
+) -> Tuple[int, int, int, int]:
+    center_x, center_y = center_coordinates
+    text_w, text_h = text_wh
+
+    if position == Position.TOP_LEFT:
+        return center_x, center_y - text_h, center_x + text_w, center_y
+    elif position == Position.TOP_RIGHT:
+        return center_x - text_w, center_y - text_h, center_x, center_y
+    elif position == Position.TOP_CENTER:
+        return (
+            center_x - text_w // 2,
+            center_y - text_h,
+            center_x + text_w // 2,
+            center_y,
+        )
+    elif position == Position.CENTER or position == Position.CENTER_OF_MASS:
+        return (
+            center_x - text_w // 2,
+            center_y - text_h // 2,
+            center_x + text_w // 2,
+            center_y + text_h // 2,
+        )
+    elif position == Position.BOTTOM_LEFT:
+        return center_x, center_y, center_x + text_w, center_y + text_h
+    elif position == Position.BOTTOM_RIGHT:
+        return center_x - text_w, center_y, center_x, center_y + text_h
+    elif position == Position.BOTTOM_CENTER:
+        return (
+            center_x - text_w // 2,
+            center_y,
+            center_x + text_w // 2,
+            center_y + text_h,
+        )
+    elif position == Position.CENTER_LEFT:
+        return (
+            center_x - text_w,
+            center_y - text_h // 2,
+            center_x,
+            center_y + text_h // 2,
+        )
+    elif position == Position.CENTER_RIGHT:
+        return (
+            center_x,
+            center_y - text_h // 2,
+            center_x + text_w,
+            center_y + text_h // 2,
+        )
+
+
 def get_color_by_index(color: Union[Color, ColorPalette], idx: int) -> Color:
     if isinstance(color, ColorPalette):
         return color.by_idx(idx)

supervision/assets/list.py

@@ -18,6 +18,8 @@ class VideoAssets(Enum):
     | `SUBWAY`               | `subway.mp4`               | [Link](https://media.roboflow.com/supervision/video-examples/subway.mp4)              |
     | `MARKET_SQUARE`        | `market-square.mp4`        | [Link](https://media.roboflow.com/supervision/video-examples/market-square.mp4)       |
     | `PEOPLE_WALKING`       | `people-walking.mp4`       | [Link](https://media.roboflow.com/supervision/video-examples/people-walking.mp4)      |
+    | `BEACH`                | `beach-1.mp4`              | [Link](https://media.roboflow.com/supervision/video-examples/beach-1.mp4)             |
+    | `BASKETBALL`           | `basketball-1.mp4`         | [Link](https://media.roboflow.com/supervision/video-examples/basketball-1.mp4)        |
     """  # noqa: E501 // docs
 
     VEHICLES = "vehicles.mp4"
@@ -27,6 +29,8 @@ class VideoAssets(Enum):
     SUBWAY = "subway.mp4"
     MARKET_SQUARE = "market-square.mp4"
     PEOPLE_WALKING = "people-walking.mp4"
+    BEACH = "beach-1.mp4"
+    BASKETBALL = "basketball-1.mp4"
 
     @classmethod
     def list(cls):
@@ -62,4 +66,12 @@ VIDEO_ASSETS: Dict[str, Tuple[str, str]] = {
         f"{BASE_VIDEO_URL}{VideoAssets.PEOPLE_WALKING.value}",
         "0574c053c8686c3f1dc0aa3743e45cb9",
     ),
+    VideoAssets.BEACH.value: (
+        f"{BASE_VIDEO_URL}{VideoAssets.BEACH.value}",
+        "4175d42fec4d450ed081523fd39e0cf8",
+    ),
+    VideoAssets.BASKETBALL.value: (
+        f"{BASE_VIDEO_URL}{VideoAssets.BASKETBALL.value}",
+        "60d94a3c7c47d16f09d342b088012ecc",
+    ),
 }

supervision/dataset/core.py

@@ -116,13 +116,12 @@ class DetectionDataset(BaseDataset):
             Tuple[DetectionDataset, DetectionDataset]: A tuple containing
                 the training and testing datasets.
 
-        Example:
+        Examples:
             ```python
             import supervision as sv
 
             ds = sv.DetectionDataset(...)
-            train_ds, test_ds = ds.split(split_ratio=0.7,
-                                         random_state=42, shuffle=True)
+            train_ds, test_ds = ds.split(split_ratio=0.7, random_state=42, shuffle=True)
             len(train_ds), len(test_ds)
             # (700, 300)
             ```
@@ -229,7 +228,7 @@ class DetectionDataset(BaseDataset):
             DetectionDataset: A DetectionDataset instance containing
                 the loaded images and annotations.
 
-        Example:
+        Examples:
             ```python
             import roboflow
             from roboflow import Roboflow
@@ -286,7 +285,7 @@ class DetectionDataset(BaseDataset):
             DetectionDataset: A DetectionDataset instance
                 containing the loaded images and annotations.
 
-        Example:
+        Examples:
             ```python
             import roboflow
             from roboflow import Roboflow
@@ -391,7 +390,7 @@ class DetectionDataset(BaseDataset):
             DetectionDataset: A DetectionDataset instance containing
                 the loaded images and annotations.
 
-        Example:
+        Examples:
             ```python
             import roboflow
             from roboflow import Roboflow
@@ -431,6 +430,20 @@ class DetectionDataset(BaseDataset):
         Exports the dataset to COCO format. This method saves the
         images and their corresponding annotations in COCO format.
 
+        !!! tip
+
+            The format of the mask is determined automatically based on its structure:
+
+            - If a mask contains multiple disconnected components or holes, it will be
+            saved using the Run-Length Encoding (RLE) format for efficient storage and
+            processing.
+            - If a mask consists of a single, contiguous region without any holes, it
+            will be encoded as a polygon, preserving the outline of the object.
+
+            This automatic selection ensures that the masks are stored in the most
+            appropriate and space-efficient format, complying with COCO dataset
+            standards.
+
         Args:
             images_directory_path (Optional[str]): The path to the directory
                 where the images should be saved.
@@ -482,7 +495,7 @@ class DetectionDataset(BaseDataset):
             (DetectionDataset): A single `DetectionDataset` object containing
             the merged data from the input list.
 
-        Example:
+        Examples:
             ```python
             import supervision as sv
 
@@ -567,13 +580,12 @@ class ClassificationDataset(BaseDataset):
             Tuple[ClassificationDataset, ClassificationDataset]: A tuple containing
             the training and testing datasets.
 
-        Example:
+        Examples:
             ```python
             import supervision as sv
 
             cd = sv.ClassificationDataset(...)
-            train_cd,test_cd = cd.split(split_ratio=0.7,
-                                        random_state=42,shuffle=True)
+            train_cd,test_cd = cd.split(split_ratio=0.7, random_state=42,shuffle=True)
             len(train_cd), len(test_cd)
             # (700, 300)
             ```
@@ -635,7 +647,7 @@ class ClassificationDataset(BaseDataset):
         Returns:
             ClassificationDataset: The dataset.
 
-        Example:
+        Examples:
             ```python
             import roboflow
             from roboflow import Roboflow

supervision/dataset/formats/coco.py

@@ -5,13 +5,20 @@ from typing import Dict, List, Tuple
 
 import cv2
 import numpy as np
+import numpy.typing as npt
 
 from supervision.dataset.utils import (
     approximate_mask_with_polygons,
     map_detections_class_id,
+    mask_to_rle,
+    rle_to_mask,
 )
 from supervision.detection.core import Detections
-from supervision.detection.utils import polygon_to_mask
+from supervision.detection.utils import (
+    contains_holes,
+    contains_multiple_segments,
+    polygon_to_mask,
+)
 from supervision.utils.file import read_json_file, save_json_file
 
 
@@ -57,13 +64,24 @@ def group_coco_annotations_by_image_id(
     return annotations
 
 
-def _polygons_to_masks(
-    polygons: List[np.ndarray], resolution_wh: Tuple[int, int]
-) -> np.ndarray:
+def coco_annotations_to_masks(
+    image_annotations: List[dict], resolution_wh: Tuple[int, int]
+) -> npt.NDArray[np.bool_]:
     return np.array(
         [
-            polygon_to_mask(polygon=polygon, resolution_wh=resolution_wh)
-            for polygon in polygons
+            rle_to_mask(
+                rle=np.array(image_annotation["segmentation"]["counts"]),
+                resolution_wh=resolution_wh,
+            )
+            if image_annotation["iscrowd"]
+            else polygon_to_mask(
+                polygon=np.reshape(
+                    np.asarray(image_annotation["segmentation"], dtype=np.int32),
+                    (-1, 2),
+                ),
+                resolution_wh=resolution_wh,
+            )
+            for image_annotation in image_annotations
         ],
         dtype=bool,
     )
@@ -83,13 +101,9 @@ def coco_annotations_to_detections(
     xyxy[:, 2:4] += xyxy[:, 0:2]
 
     if with_masks:
-        polygons = [
-            np.reshape(
-                np.asarray(image_annotation["segmentation"], dtype=np.int32), (-1, 2)
-            )
-            for image_annotation in image_annotations
-        ]
-        mask = _polygons_to_masks(polygons=polygons, resolution_wh=resolution_wh)
+        mask = coco_annotations_to_masks(
+            image_annotations=image_annotations, resolution_wh=resolution_wh
+        )
         return Detections(
             class_id=np.asarray(class_ids, dtype=int), xyxy=xyxy, mask=mask
         )
@@ -108,24 +122,35 @@ def detections_to_coco_annotations(
     coco_annotations = []
     for xyxy, mask, _, class_id, _, _ in detections:
         box_width, box_height = xyxy[2] - xyxy[0], xyxy[3] - xyxy[1]
-        polygon = []
+        segmentation = []
+        iscrowd = 0
         if mask is not None:
-            polygon = list(
-                approximate_mask_with_polygons(
-                    mask=mask,
-                    min_image_area_percentage=min_image_area_percentage,
-                    max_image_area_percentage=max_image_area_percentage,
-                    approximation_percentage=approximation_percentage,
-                )[0].flatten()
-            )
+            iscrowd = contains_holes(mask=mask) or contains_multiple_segments(mask=mask)
+
+            if iscrowd:
+                segmentation = {
+                    "counts": mask_to_rle(mask=mask),
+                    "size": list(mask.shape[:2]),
+                }
+            else:
+                segmentation = [
+                    list(
+                        approximate_mask_with_polygons(
+                            mask=mask,
+                            min_image_area_percentage=min_image_area_percentage,
+                            max_image_area_percentage=max_image_area_percentage,
+                            approximation_percentage=approximation_percentage,
+                        )[0].flatten()
+                    )
+                ]
         coco_annotation = {
             "id": annotation_id,
             "image_id": image_id,
             "category_id": int(class_id),
             "bbox": [xyxy[0], xyxy[1], box_width, box_height],
             "area": box_width * box_height,
-            "segmentation": [polygon] if polygon else [],
-            "iscrowd": 0,
+            "segmentation": segmentation,
+            "iscrowd": iscrowd,
         }
         coco_annotations.append(coco_annotation)
         annotation_id += 1

supervision/dataset/utils.py

@@ -2,10 +2,11 @@ import copy
 import os
 import random
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple, TypeVar
+from typing import Dict, List, Optional, Tuple, TypeVar, Union
 
 import cv2
 import numpy as np
+import numpy.typing as npt
 
 from supervision.detection.core import Detections
 from supervision.detection.utils import (
@@ -129,3 +130,123 @@ def train_test_split(
 
     split_index = int(len(data) * train_ratio)
     return data[:split_index], data[split_index:]
+
+
+def rle_to_mask(
+    rle: Union[npt.NDArray[np.int_], List[int]], resolution_wh: Tuple[int, int]
+) -> npt.NDArray[np.bool_]:
+    """
+    Converts run-length encoding (RLE) to a binary mask.
+
+    Args:
+        rle (Union[npt.NDArray[np.int_], List[int]]): The 1D RLE array, the format
+            used in the COCO dataset (column-wise encoding, values of an array with
+            even indices represent the number of pixels assigned as background,
+            values of an array with odd indices represent the number of pixels
+            assigned as foreground object).
+        resolution_wh (Tuple[int, int]): The width (w) and height (h)
+            of the desired binary mask.
+
+    Returns:
+        The generated 2D Boolean mask of shape `(h, w)`, where the foreground object is
+            marked with `True`'s and the rest is filled with `False`'s.
+
+    Raises:
+        AssertionError: If the sum of pixels encoded in RLE differs from the
+            number of pixels in the expected mask (computed based on resolution_wh).
+
+    Examples:
+        ```python
+        import supervision as sv
+
+        sv.rle_to_mask([5, 2, 2, 2, 5], (4, 4))
+        # array([
+        #     [False, False, False, False],
+        #     [False, True,  True,  False],
+        #     [False, True,  True,  False],
+        #     [False, False, False, False],
+        # ])
+        ```
+    """
+    if isinstance(rle, list):
+        rle = np.array(rle, dtype=int)
+
+    width, height = resolution_wh
+
+    assert width * height == np.sum(rle), (
+        "the sum of the number of pixels in the RLE must be the same "
+        "as the number of pixels in the expected mask"
+    )
+
+    zero_one_values = np.zeros(shape=(rle.size, 1), dtype=np.uint8)
+    zero_one_values[1::2] = 1
+
+    decoded_rle = np.repeat(zero_one_values, rle, axis=0)
+    decoded_rle = np.append(
+        decoded_rle, np.zeros(width * height - len(decoded_rle), dtype=np.uint8)
+    )
+    return decoded_rle.reshape((height, width), order="F")
+
+
+def mask_to_rle(mask: npt.NDArray[np.bool_]) -> List[int]:
+    """
+    Converts a binary mask into a run-length encoding (RLE).
+
+    Args:
+        mask (npt.NDArray[np.bool_]): 2D binary mask where `True` indicates foreground
+            object and `False` indicates background.
+
+    Returns:
+        The run-length encoded mask. Values of a list with even indices
+            represent the number of pixels assigned as background (`False`), values
+            of a list with odd indices represent the number of pixels assigned
+            as foreground object (`True`).
+
+    Raises:
+        AssertionError: If input mask is not 2D or is empty.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        mask = np.array([
+            [True, True, True, True],
+            [True, True, True, True],
+            [True, True, True, True],
+            [True, True, True, True],
+        ])
+        sv.mask_to_rle(mask)
+        # [0, 16]
+
+        mask = np.array([
+            [False, False, False, False],
+            [False, True,  True,  False],
+            [False, True,  True,  False],
+            [False, False, False, False],
+        ])
+        sv.mask_to_rle(mask)
+        # [5, 2, 2, 2, 5]
+        ```
+
+    ![mask_to_rle](https://media.roboflow.com/supervision-docs/mask-to-rle.png){ align=center width="800" }
+    """  # noqa E501 // docs
+    assert mask.ndim == 2, "Input mask must be 2D"
+    assert mask.size != 0, "Input mask cannot be empty"
+
+    on_value_change_indices = np.where(
+        mask.ravel(order="F") != np.roll(mask.ravel(order="F"), 1)
+    )[0]
+
+    on_value_change_indices = np.append(on_value_change_indices, mask.size)
+    # need to add 0 at the beginning when the same value is in the first and
+    # last element of the flattened mask
+    if on_value_change_indices[0] != 0:
+        on_value_change_indices = np.insert(on_value_change_indices, 0, 0)
+
+    rle = np.diff(on_value_change_indices)
+
+    if mask[0][0] == 1:
+        rle = np.insert(rle, 0, 0)
+
+    return list(rle)

supervision/detection/annotate.py

@@ -1,17 +1,14 @@
 from typing import List, Optional, Union
 
 import cv2
-import numpy as np
 
+from supervision.annotators.base import ImageType
 from supervision.detection.core import Detections
 from supervision.draw.color import Color, ColorPalette
+from supervision.utils.conversion import convert_for_annotation_method
 from supervision.utils.internal import deprecated
 
 
-@deprecated(
-    "`BoxAnnotator` is deprecated and will be removed in "
-    "`supervision-0.22.0`. Use `BoundingBoxAnnotator` and `LabelAnnotator` instead"
-)
 class BoxAnnotator:
     """
     A class for drawing bounding boxes on an image using detections provided.
@@ -45,18 +42,25 @@ class BoxAnnotator:
         self.text_thickness: int = text_thickness
         self.text_padding: int = text_padding
 
+    @deprecated(
+        "`BoxAnnotator` is deprecated and will be removed in "
+        "`supervision-0.22.0`. Use `BoundingBoxAnnotator` and `LabelAnnotator` instead"
+    )
+    @convert_for_annotation_method
     def annotate(
         self,
-        scene: np.ndarray,
+        scene: ImageType,
         detections: Detections,
         labels: Optional[List[str]] = None,
         skip_label: bool = False,
-    ) -> np.ndarray:
+    ) -> ImageType:
         """
         Draws bounding boxes on the frame using the detections provided.
 
         Args:
-            scene (np.ndarray): The image on which the bounding boxes will be drawn
+            scene (ImageType): The image on which the bounding boxes will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
             detections (Detections): The detections for which the
                 bounding boxes will be drawn
             labels (Optional[List[str]]): An optional list of labels
@@ -64,7 +68,8 @@ class BoxAnnotator:
                 corresponding `class_id` will be used as label.
             skip_label (bool): Is set to `True`, skips bounding box label annotation.
         Returns:
-            np.ndarray: The image with the bounding boxes drawn on it
+            ImageType: The image with the bounding boxes drawn on it, matching the
+                type of `scene` (`numpy.ndarray` or `PIL.Image.Image`)
 
         Example:
             ```python