Merge pull request #1573 from roboflow/develop

supervision-0.24.0 release

.github/workflows/notebook-bot.yml

@@ -0,0 +1,64 @@
+name: Notebook Check Pull Request
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  comment-welcome:
+    permissions:
+      contents: read
+      pull-requests: write
+
+    runs-on: ubuntu-latest
+    steps:
+    - name: Fetch pull request branch
+      uses: actions/checkout@v4
+      with:
+        repository: ${{ github.event.pull_request.head.repo.full_name }}
+        ref: ${{ github.event.pull_request.head.sha }}
+    - name: Fetch base develop branch
+      run: git fetch -u "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY" develop:develop
+    - name: Create message
+      env:
+        HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}
+        HEAD_REF: ${{ github.event.pull_request.head.ref }}
+        PR_NUM: ${{ github.event.pull_request.number }}
+      run: |
+        # Preview links and tool usage only needed for notebook changes.
+        readarray -t changed_notebooks < <(git diff --name-only develop | grep '\.ipynb$' || true)
+        if [[ ${#changed_notebooks[@]} == 0 ]]; then
+          echo "No notebooks modified in this pull request."
+        else
+          msg="<h4>Preview</h4>\n"
+          msg+="Preview and run these notebook edits with Google Colab:\n<ul>\n"
+          # Link to PR branch in user's fork that is always current.
+          for fp in "${changed_notebooks[@]}"; do
+            gh_path="${HEAD_REPOSITORY}/blob/${HEAD_REF}/${fp}"
+            colab_url="https://colab.research.google.com/github/${gh_path}"
+            msg+="<li><a href='${colab_url}'>${fp}</a></li>\n"
+          done
+          msg+="</ul>\n"
+
+          reviewnb_url="https://app.reviewnb.com/${GITHUB_REPOSITORY}/pull/${PR_NUM}/files/"
+          msg+="Rendered <a href='${reviewnb_url}'>notebook diffs</a> available on ReviewNB.com.\n"
+
+          msg+="If commits are added to the pull request, synchronize your local branch: <code>git pull origin $HEAD_REF</code>\n"
+        fi
+        echo "MESSAGE=$msg" >> $GITHUB_ENV
+    - name: Post comment
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        ISSUE_URL: ${{ github.event.pull_request.issue_url }}
+      run: |
+        # Env var defined in previous step. Escape string for JSON.
+        body="$(echo -n -e $MESSAGE | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+        # Add comment to pull request.
+        curl -X POST \
+          -H "Accept: application/vnd.github.v3+json" \
+          -H "Authorization: token $GITHUB_TOKEN" \
+          "${ISSUE_URL}/comments" \
+          --data "{\"body\": $body}"

.github/workflows/publish-test.yml

@@ -1,4 +1,4 @@
-name: Supervision Test Releases to PyPi
+name: Publish Supervision Pre-Releases to PyPI and TestPyPI
 on:
   push:
     tags:
@@ -9,9 +9,11 @@ on:
   workflow_dispatch:
 
 jobs:
-  build-n-publish:
+  build-and-publish-pre-release-pypi:
     name: Build and publish to PyPI
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
     strategy:
       matrix:
         python-version: ["3.10"]
@@ -30,14 +32,11 @@ jobs:
           python -m pip install --upgrade build twine
           python -m build
           twine check --strict dist/*
-      - name: 🚀 Publish distribution to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          user: ${{ secrets.PYPI_USERNAME }}
-          password: ${{ secrets.PYPI_PASSWORD }}
+
+      - name: 🚀 Publish to PyPi
+        uses: pypa/gh-action-pypi-publish@release/v1.10
+
       - name: 🚀 Publish to Test-PyPi
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@release/v1.10
         with:
           repository-url: https://test.pypi.org/legacy/
-          user: ${{ secrets.PYPI_TEST_USERNAME }}
-          password: ${{ secrets.PYPI_TEST_PASSWORD }}

.github/workflows/publish.yml

@@ -1,4 +1,4 @@
-name: Supervision Releases to PyPi
+name: Publish Supervision Releases to PyPI and TestPyPI
 on:
   push:
     tags:
@@ -7,8 +7,10 @@ on:
   workflow_dispatch:
 
 jobs:
-  build:
+  build-and-publish-pre-release:
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
     strategy:
       matrix:
         python-version: ["3.10"]
@@ -27,14 +29,11 @@ jobs:
           python -m pip install --upgrade build twine
           python -m build
           twine check --strict dist/*
+
       - name: 🚀 Publish to PyPi
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          user: ${{ secrets.PYPI_USERNAME }}
-          password: ${{ secrets.PYPI_PASSWORD }}
+        uses: pypa/gh-action-pypi-publish@release/v1.10
+
       - name: 🚀 Publish to Test-PyPi
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@release/v1.10
         with:
           repository-url: https://test.pypi.org/legacy/
-          user: ${{ secrets.PYPI_TEST_USERNAME }}
-          password: ${{ secrets.PYPI_TEST_PASSWORD }}

.github/workflows/test-doc.yml

@@ -14,21 +14,8 @@ jobs:
         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
+      - name:  🏗️ Install dependencies and Test Docs Build
+        run: |
+          python -m pip install --upgrade pip
+          pip install "mkdocs-material" "mkdocstrings[python]" "mkdocs-material[imaging]" mike "mkdocs-git-revision-date-localized-plugin" jupyterlab mkdocs-jupyter mkdocs-git-committers-plugin-2
+          mkdocs build --verbose

.pre-commit-config.yaml

@@ -9,7 +9,6 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0
     hooks:
-      - id: end-of-file-fixer
       - id: trailing-whitespace
         exclude: test/.*\.py
       - id: check-yaml
@@ -19,35 +18,38 @@ repos:
       - id: check-case-conflict
       - id: check-added-large-files
       - id: detect-private-key
-      - id: forbid-new-submodules
       - id: pretty-format-json
         exclude: demo.ipynb
         args: ['--autofix', '--no-sort-keys', '--indent=4']
       - id: end-of-file-fixer
       - id: mixed-line-ending
 
-
   -   repo: https://github.com/PyCQA/bandit
-      rev: '1.7.9'
+      rev: '1.7.10'
       hooks:
       -   id: bandit
           args: ["-c", "pyproject.toml"]
           additional_dependencies: ["bandit[toml]"]
 
-  -   repo: https://github.com/pycqa/isort
-      rev: 5.13.2
-      hooks:
-      -   id: isort
-          name: isort (python)
-      -   id: isort
-          name: isort (pyi)
-          types: [pyi]
-
-
   -   repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.5.1
+      rev: v0.6.8
       hooks:
       -   id: ruff
           args: [--fix, --exit-non-zero-on-fix]
       -   id: ruff-format
           types_or: [ python, pyi, jupyter ]
+
+  # - repo: https://github.com/executablebooks/mdformat
+  #   rev: 0.7.17
+  #   hooks:
+  #     - id: mdformat
+  #       additional_dependencies:
+  #         - "mdformat-mkdocs[recommended]>=2.1.0"
+  #       args: ["--number"]
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli

CODE_OF_CONDUCT.md

@@ -1,4 +1,3 @@
-
 # Contributor Covenant Code of Conduct
 
 ## Our Pledge
@@ -6,7 +5,7 @@
 We as members, contributors, and leaders pledge to make participation in our
 community a harassment-free experience for everyone, regardless of age, body
 size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
+identity and expression, level of experience, education, socioeconomic status,
 nationality, personal appearance, race, caste, color, religion, or sexual
 identity and orientation.
 
@@ -18,23 +17,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
+- Focusing on what is best not just for us as individuals, but for the overall
   community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or advances of
+- The use of sexualized language or imagery, and sexual attention or advances of
   any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
   without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities
@@ -121,14 +120,14 @@ version 2.1, available at
 [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
 
 Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+[Mozilla's code of conduct enforcement ladder][mozilla coc].
 
 For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
 [https://www.contributor-covenant.org/translations][translations].
 
+[faq]: https://www.contributor-covenant.org/faq
 [homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
+[mozilla coc]: https://github.com/mozilla/diversity
 [translations]: https://www.contributor-covenant.org/translations
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

CONTRIBUTING.md

@@ -6,22 +6,22 @@ We are actively improving this library to reduce the amount of work you need to
 
 ## Code of Conduct
 
-Please read and adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). This document outlines the expected behavior for all participants in our project.
+Please read and adhere to our [Code of Conduct](https://supervision.roboflow.com/latest/code_of_conduct/). This document outlines the expected behavior for all participants in our project.
 
 ## Table of Contents
 
 - [Contribution Guidelines](#contribution-guidelines)
-  - [Contributing Features](#contributing-features-)
+    - [Contributing Features](#contributing-features)
 - [How to Contribute Changes](#how-to-contribute-changes)
 - [Installation for Contributors](#installation-for-contributors)
-- [Code Style and Quality](#-code-style-and-quality)
-  - [Pre-commit tool](#pre-commit-tool)
-  - [Docstrings](#docstrings)
-  - [Type checking](#type-checking)
-- [Documentation](#-documentation)
-- [Cookbooks](#-cookbooks)
-- [Tests](#-tests)
-- [License](#-license)
+- [Code Style and Quality](#code-style-and-quality)
+    - [Pre-commit tool](#pre-commit-tool)
+    - [Docstrings](#docstrings)
+    - [Type checking](#type-checking)
+- [Documentation](#documentation)
+- [Cookbooks](#cookbooks)
+- [Tests](#tests)
+- [License](#license)
 
 ## Contribution Guidelines
 
@@ -83,9 +83,10 @@ git push -u origin <your_branch_name>
 
 Use conventional commit messages to clearly describe your changes. The format is:
 
-<type>[optional scope]: <description>
+<type>\[optional scope\]: <description>
 
 Common types include:
+
 - feat: A new feature
 - fix: A bug fix
 - docs: Documentation only changes
@@ -128,40 +129,47 @@ PRs must pass all tests and linting requirements before they can be merged.
 Before starting your work on the project, set up your development environment:
 
 1. Clone your fork of the project:
-   ```bash
-   git clone https://github.com/YOUR_USERNAME/supervision.git
-   cd supervision
-   ```
-   Replace `YOUR_USERNAME` with your GitHub username.
+
+    ```bash
+    git clone https://github.com/YOUR_USERNAME/supervision.git
+    cd supervision
+    ```
+
+    Replace `YOUR_USERNAME` with your GitHub username.
 
 2. Create and activate a virtual environment:
-   ```bash
-   python3 -m venv .venv
-   source .venv/bin/activate
-   ```
+
+    ```bash
+    python3 -m venv .venv
+    source .venv/bin/activate
+    ```
 
 3. Install Poetry:
 
-   Using pip:
-   ```bash
-   pip install -U pip setuptools
-   pip install poetry
-   ```
+    Using pip:
 
-   Or using pipx (recommended for global installation):
-   ```bash
-   pipx install poetry
-   ```
+    ```bash
+    pip install -U pip setuptools
+    pip install poetry
+    ```
+
+    Or using pipx (recommended for global installation):
+
+    ```bash
+    pipx install poetry
+    ```
 
 4. Install project dependencies:
-   ```bash
-   poetry install
-   ```
+
+    ```bash
+    poetry install
+    ```
 
 5. Run pytest to verify the setup:
-   ```bash
-   poetry run pytest
-   ```
+
+    ```bash
+    poetry run pytest
+    ```
 
 ## 🎨 Code Style and Quality
 
@@ -173,7 +181,7 @@ Furthermore, we have integrated a pre-commit GitHub Action into our workflow. Th
 
 To run the pre-commit tool, follow these steps:
 
-1. Install pre-commit by running the following command: `poetry install`. It will not only install pre-commit but also install all the deps and dev-deps of project
+1. Install pre-commit by running the following command: `poetry install --with dev`. It will not only install pre-commit but also install all the deps and dev-deps of project
 
 2. Once pre-commit is installed, navigate to the project's root directory.
 

README.md

@@ -8,27 +8,33 @@
     </a>
   </p>
 
-  <br>
+<br>
 
 [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>
+<br>
 
 [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
 [![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision)
+[![snyk](https://snyk.io/advisor/python/supervision/badge.svg)](https://snyk.io/advisor/python/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)
 [![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 align="center">
+    <a href="https://trendshift.io/repositories/124"  target="_blank"><img src="https://trendshift.io/api/badge/repositories/124" alt="roboflow%2Fsupervision | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+  </div>
+
 </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)
+[![supervision-hackfest](https://media.roboflow.com/supervision/supervision-hacktoberfest-banner-2024.png)](https://github.com/roboflow/supervision/issues?q=is%3Aissue+is%3Aopen+label%3Ahacktoberfest)
 
 ## 💻 install
 
@@ -53,7 +59,7 @@ import supervision as sv
 from ultralytics import YOLO
 
 image = cv2.imread(...)
-model = YOLO('yolov8s.pt')
+model = YOLO("yolov8s.pt")
 result = model(image)[0]
 detections = sv.Detections.from_ultralytics(result)
 
@@ -66,21 +72,21 @@ len(detections)
 
 - inference
 
-    Running with [Inference](https://github.com/roboflow/inference) requires a [Roboflow API KEY](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key).
+  Running with [Inference](https://github.com/roboflow/inference) requires a [Roboflow API KEY](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key).
 
-    ```python
-    import cv2
-    import supervision as sv
-    from inference import get_model
+  ```python
+  import cv2
+  import supervision as sv
+  from inference import get_model
 
-    image = cv2.imread(...)
-    model = get_model(model_id="yolov8s-640", api_key=<ROBOFLOW API KEY>)
-    result = model.infer(image)[0]
-    detections = sv.Detections.from_inference(result)
+  image = cv2.imread(...)
+  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
-    ```
+  len(detections)
+  # 5
+  ```
 
 </details>
 
@@ -97,9 +103,8 @@ detections = sv.Detections(...)
 
 box_annotator = sv.BoxAnnotator()
 annotated_frame = box_annotator.annotate(
-    scene=image.copy(),
-    detections=detections
-)
+  scene=image.copy(),
+  detections=detections)
 ```
 
 https://github.com/roboflow/supervision/assets/26109316/691e219c-0565-4403-9218-ab5644f39bce
@@ -110,18 +115,21 @@ Supervision provides a set of [utils](https://supervision.roboflow.com/latest/da
 
 ```python
 import supervision as sv
+from roboflow import Roboflow
 
-dataset = sv.DetectionDataset.from_yolo(
-    images_directory_path=...,
-    annotations_directory_path=...,
-    data_yaml_path=...
+project = Roboflow().workspace(<WORKSPACE_ID>).project(<PROJECT_ID>)
+dataset = project.version(<PROJECT_VERSION>).download("coco")
+
+ds = sv.DetectionDataset.from_coco(
+    images_directory_path=f"{dataset.location}/train",
+    annotations_path=f"{dataset.location}/train/_annotations.coco.json",
 )
 
-dataset.classes
-['dog', 'person']
+path, image, annotation = ds[0]
+    # loads image on demand
 
-len(dataset)
-# 1000
+for path, image, annotation in ds:
+    # loads image on demand
 ```
 
 <details close>
@@ -129,88 +137,88 @@ len(dataset)
 
 - load
 
-  ```python
-  dataset = sv.DetectionDataset.from_yolo(
-      images_directory_path=...,
-      annotations_directory_path=...,
-      data_yaml_path=...
-  )
+    ```python
+    dataset = sv.DetectionDataset.from_yolo(
+        images_directory_path=...,
+        annotations_directory_path=...,
+        data_yaml_path=...
+    )
 
-  dataset = sv.DetectionDataset.from_pascal_voc(
-      images_directory_path=...,
-      annotations_directory_path=...
-  )
+    dataset = sv.DetectionDataset.from_pascal_voc(
+        images_directory_path=...,
+        annotations_directory_path=...
+    )
 
-  dataset = sv.DetectionDataset.from_coco(
-      images_directory_path=...,
-      annotations_path=...
-  )
-  ```
+    dataset = sv.DetectionDataset.from_coco(
+        images_directory_path=...,
+        annotations_path=...
+    )
+    ```
 
 - split
 
-  ```python
-  train_dataset, test_dataset = dataset.split(split_ratio=0.7)
-  test_dataset, valid_dataset = test_dataset.split(split_ratio=0.5)
+    ```python
+    train_dataset, test_dataset = dataset.split(split_ratio=0.7)
+    test_dataset, valid_dataset = test_dataset.split(split_ratio=0.5)
 
-  len(train_dataset), len(test_dataset), len(valid_dataset)
-  # (700, 150, 150)
-  ```
+    len(train_dataset), len(test_dataset), len(valid_dataset)
+    # (700, 150, 150)
+    ```
 
 - merge
 
-  ```python
-  ds_1 = sv.DetectionDataset(...)
-  len(ds_1)
-  # 100
-  ds_1.classes
-  # ['dog', 'person']
+    ```python
+    ds_1 = sv.DetectionDataset(...)
+    len(ds_1)
+    # 100
+    ds_1.classes
+    # ['dog', 'person']
 
-  ds_2 = sv.DetectionDataset(...)
-  len(ds_2)
-  # 200
-  ds_2.classes
-  # ['cat']
+    ds_2 = sv.DetectionDataset(...)
+    len(ds_2)
+    # 200
+    ds_2.classes
+    # ['cat']
 
-  ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
-  len(ds_merged)
-  # 300
-  ds_merged.classes
-  # ['cat', 'dog', 'person']
-  ```
+    ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
+    len(ds_merged)
+    # 300
+    ds_merged.classes
+    # ['cat', 'dog', 'person']
+    ```
 
 - save
 
-  ```python
-  dataset.as_yolo(
-      images_directory_path=...,
-      annotations_directory_path=...,
-      data_yaml_path=...
-  )
+    ```python
+    dataset.as_yolo(
+        images_directory_path=...,
+        annotations_directory_path=...,
+        data_yaml_path=...
+    )
 
-  dataset.as_pascal_voc(
-      images_directory_path=...,
-      annotations_directory_path=...
-  )
+    dataset.as_pascal_voc(
+        images_directory_path=...,
+        annotations_directory_path=...
+    )
 
-  dataset.as_coco(
-      images_directory_path=...,
-      annotations_path=...
-  )
-  ```
+    dataset.as_coco(
+        images_directory_path=...,
+        annotations_path=...
+    )
+    ```
 
 - convert
 
-  ```python
-  sv.DetectionDataset.from_yolo(
-      images_directory_path=...,
-      annotations_directory_path=...,
-      data_yaml_path=...
-  ).as_pascal_voc(
-      images_directory_path=...,
-      annotations_directory_path=...
-  )
-  ```
+    ```python
+    sv.DetectionDataset.from_yolo(
+        images_directory_path=...,
+        annotations_directory_path=...,
+        data_yaml_path=...
+    ).as_pascal_voc(
+        images_directory_path=...,
+        annotations_directory_path=...
+    )
+    ```
 
 </details>
 
@@ -262,7 +270,7 @@ We love your input! Please see our [contributing guide](https://github.com/robof
 
 <div align="center">
 
-  <div align="center">
+<div align="center">
       <a href="https://youtube.com/roboflow">
           <img
             src="https://media.roboflow.com/notebooks/template/icons/purple/youtube.png?ik-sdk-version=javascript-1.4.3&updatedAt=1672949634652"
@@ -291,7 +299,7 @@ We love your input! Please see our [contributing guide](https://github.com/robof
           />
       </a>
       <img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%"/>
-      <a href="https://disuss.roboflow.com">
+      <a href="https://discuss.roboflow.com">
           <img
             src="https://media.roboflow.com/notebooks/template/icons/purple/forum.png?ik-sdk-version=javascript-1.4.3&updatedAt=1672949633584"
             width="3%"

demo.ipynb

@@ -972,7 +972,7 @@
     }
    ],
    "source": [
-    "from supervision.assets import download_assets, VideoAssets\n",
+    "from supervision.assets import VideoAssets, download_assets\n",
     "\n",
     "download_assets(VideoAssets.VEHICLES)\n",
     "VIDEO_PATH = VideoAssets.VEHICLES.value"
@@ -1357,7 +1357,7 @@
     }
    ],
    "source": [
-    "IMAGE_NAME = list(ds.images.keys())[0]\n",
+    "IMAGE_NAME = next(iter(ds.images.keys()))\n",
     "\n",
     "image = ds.images[IMAGE_NAME]\n",
     "annotations = ds.annotations[IMAGE_NAME]\n",

docs/assets.md

@@ -13,7 +13,6 @@ To install the Supervision assets utility, you can use `pip`. This utility is av
 as an extra within the Supervision package.
 
 !!! example "pip install"
-
     ```bash
     pip install "supervision[assets]"
     ```

docs/changelog.md

@@ -1,6 +1,279 @@
+# CHANGELOG
+
+### 0.24.0 <small>Oct 4, 2024</small>
+
+- Added [F1 score](https://supervision.roboflow.com/0.24.0/metrics/f1_score/#supervision.metrics.f1_score.F1Score) as a new metric for detection and segmentation. [#1521](https://github.com/roboflow/supervision/pull/1521)
+
+```python
+import supervision as sv
+from supervision.metrics import F1Score
+
+predictions = sv.Detections(...)
+targets = sv.Detections(...)
+
+f1_metric = F1Score()
+f1_result = f1_metric.update(predictions, targets).compute()
+
+print(f1_result)
+print(f1_result.f1_50)
+print(f1_result.small_objects.f1_50)
+```
+
+- Added new cookbook: [Small Object Detection with SAHI](https://supervision.roboflow.com/0.24.0/notebooks/small-object-detection-with-sahi/). This cookbook provides a detailed guide on using [`InferenceSlicer`](https://supervision.roboflow.com/0.24.0/detection/tools/inference_slicer/) for small object detection. [#1483](https://github.com/roboflow/supervision/pull/1483)
+
+- Added an [Embedded Workflow](https://roboflow.com/workflows), which allows you to [preview annotators](https://supervision.roboflow.com/0.24.0/detection/annotators/). [#1533](https://github.com/roboflow/supervision/pull/1533)
+
+- Enhanced [`LineZoneAnnotator`](https://supervision.roboflow.com/0.24.0/detection/tools/line_zone/#supervision.detection.line_zone.LineZoneAnnotator), allowing the labels to align with the line, even when it's not horizontal. Also, you can now disable text background, and choose to draw labels off-center which minimizes overlaps for multiple [`LineZone`](https://supervision.roboflow.com/0.24.0/detection/tools/line_zone/#supervision.detection.line_zone.LineZone) labels. [#854](https://github.com/roboflow/supervision/pull/854)
+
+```python
+import supervision as sv
+import cv2
+
+image = cv2.imread("<SOURCE_IMAGE_PATH>")
+
+line_zone = sv.LineZone(
+    start=sv.Point(0, 100),
+    end=sv.Point(50, 200)
+)
+line_zone_annotator = sv.LineZoneAnnotator(
+    text_orient_to_line=True,
+    display_text_box=False,
+    text_centered=False
+)
+
+annotated_frame = line_zone_annotator.annotate(
+    frame=image.copy(), line_counter=line_zone
+)
+
+sv.plot_image(frame)
+```
+
+- Added per-class counting capabilities to [`LineZone`](https://supervision.roboflow.com/0.24.0/detection/tools/line_zone/#supervision.detection.line_zone.LineZone) and introduced [`LineZoneAnnotatorMulticlass`](https://supervision.roboflow.com/0.24.0/detection/tools/line_zone/#supervision.detection.line_zone.LineZoneAnnotatorMulticlass) for visualizing the counts per class. This feature allows tracking of individual classes crossing a line, enhancing the flexibility of use cases like traffic monitoring or crowd analysis. [#1555](https://github.com/roboflow/supervision/pull/1555)
+
+```python
+import supervision as sv
+import cv2
+
+image = cv2.imread("<SOURCE_IMAGE_PATH>")
+
+line_zone = sv.LineZone(
+    start=sv.Point(0, 100),
+    end=sv.Point(50, 200)
+)
+line_zone_annotator = sv.LineZoneAnnotatorMulticlass()
+
+frame = line_zone_annotator.annotate(
+    frame=frame, line_zones=[line_zone]
+)
+
+sv.plot_image(frame)
+```
+
+- Added [`from_easyocr`](https://supervision.roboflow.com/0.24.0/detection/core/#supervision.detection.core.Detections.from_easyocr), allowing integration of OCR results into the supervision framework. [EasyOCR](https://github.com/JaidedAI/EasyOCR) is an open-source optical character recognition (OCR) library that can read text from images. [#1515](https://github.com/roboflow/supervision/pull/1515)
+
+```python
+import supervision as sv
+import easyocr
+import cv2
+
+image = cv2.imread("<SOURCE_IMAGE_PATH>")
+
+reader = easyocr.Reader(["en"])
+result = reader.readtext("<SOURCE_IMAGE_PATH>", paragraph=True)
+detections = sv.Detections.from_easyocr(result)
+
+box_annotator = sv.BoxAnnotator(color_lookup=sv.ColorLookup.INDEX)
+label_annotator = sv.LabelAnnotator(color_lookup=sv.ColorLookup.INDEX)
+
+annotated_image = image.copy()
+annotated_image = box_annotator.annotate(scene=annotated_image, detections=detections)
+annotated_image = label_annotator.annotate(scene=annotated_image, detections=detections)
+
+sv.plot_image(annotated_image)
+```
+
+- Added [`oriented_box_iou_batch`](https://supervision.roboflow.com/0.24.0/detection/utils/#supervision.detection.utils.oriented_box_iou_batch) function to `detection.utils`. This function computes Intersection over Union (IoU) for oriented or rotated bounding boxes (OBB). [#1502](https://github.com/roboflow/supervision/pull/1502)
+
+```python
+import numpy as np
+
+boxes_true = np.array([[[1, 0], [0, 1], [3, 4], [4, 3]]])
+boxes_detection = np.array([[[1, 1], [2, 0], [4, 2], [3, 3]]])
+ious = sv.oriented_box_iou_batch(boxes_true, boxes_detection)
+print("IoU between true and detected boxes:", ious)
+```
+
+- Extended [`PolygonZoneAnnotator`](https://supervision.roboflow.com/0.24.0/detection/tools/polygon_zone/#supervision.detection.tools.polygon_zone.PolygonZoneAnnotator) to allow setting opacity when drawing zones, providing enhanced visualization by filling the zone with adjustable transparency. [#1527](https://github.com/roboflow/supervision/pull/1527)
+
+```python
+import cv2
+from ncnn.model_zoo import get_model
+import supervision as sv
+
+image = cv2.imread("<SOURCE_IMAGE_PATH>")
+model = get_model(
+    "yolov8s",
+    target_size=640,
+    prob_threshold=0.5,
+    nms_threshold=0.45,
+    num_threads=4,
+    use_gpu=True,
+)
+result = model(image)
+detections = sv.Detections.from_ncnn(result)
+```
+
+!!! failure "Removed"
+
+    The `frame_resolution_wh` parameter in [`PolygonZone`](https://supervision.roboflow.com/0.24.0/detection/tools/polygon_zone/#supervision.detection.tools.polygon_zone.PolygonZone) has been removed.
+
+!!! failure "Removed"
+
+    Supervision installation methods `"headless"` and `"desktop"` were removed, as they are no longer needed. `pip install supervision[headless]` will install the base library and harmlessly warn of non-existent extras.
+
+- Supervision now depends on `opencv-python` rather than `opencv-python-headless`. [#1530](https://github.com/roboflow/supervision/pull/1530)
+
+- Fixed the COCO 101 point Average Precision algorithm to correctly interpolate precision, providing a more precise calculation of average precision without averaging out intermediate values. [#1500](https://github.com/roboflow/supervision/pull/1500)
+
+- Resolved miscellaneous issues highlighted when building documentation. This mostly includes whitespace adjustments and type inconsistencies. Updated documentation for clarity and fixed formatting issues. Added explicit version for `mkdocstrings-python`. [#1549](https://github.com/roboflow/supervision/pull/1549)
+
+- Enabled and fixed Ruff rules for code formatting, including changes like avoiding unnecessary iterable allocations and using Optional for default mutable arguments. [#1526](https://github.com/roboflow/supervision/pull/1526)
+
+### 0.23.0 <small>Aug 28, 2024</small>
+
+- Added [#930](https://github.com/roboflow/supervision/pull/930): `IconAnnotator`, a [new annotator](https://supervision.roboflow.com/0.23.0/detection/annotators/#supervision.annotators.core.IconAnnotator) that allows drawing icons on each detection. Useful if you want to draw a specific icon for each class.
+
+```python
+import supervision as sv
+from inference import get_model
+
+image = <SOURCE_IMAGE_PATH>
+icon_dog = <DOG_PNG_PATH>
+icon_cat = <CAT_PNG_PATH>
+
+model = get_model(model_id="yolov8n-640")
+results = model.infer(image)[0]
+detections = sv.Detections.from_inference(results)
+
+icon_paths = []
+for class_name in detections.data["class_name"]:
+    if class_name == "dog":
+        icon_paths.append(icon_dog)
+    elif class_name == "cat":
+        icon_paths.append(icon_cat)
+    else:
+        icon_paths.append("")
+
+icon_annotator = sv.IconAnnotator()
+annotated_frame = icon_annotator.annotate(
+    scene=image.copy(),
+    detections=detections,
+    icon_path=icon_paths
+)
+```
+
+- Added [#1385](https://github.com/roboflow/supervision/pull/1385): [`BackgroundColorAnnotator`](https://supervision.roboflow.com/0.23.0/detection/annotators/#supervision.annotators.core.BackgroundColorAnnotator), that draws an overlay on the background images of the detections.
+
+```python
+import supervision as sv
+from inference import get_model
+
+image = <SOURCE_IMAGE_PATH>
+
+model = get_model(model_id="yolov8n-640")
+results = model.infer(image)[0]
+detections = sv.Detections.from_inference(results)
+
+background_overlay_annotator = sv.BackgroundOverlayAnnotator()
+annotated_frame = background_overlay_annotator.annotate(
+    scene=image.copy(),
+    detections=detections
+)
+```
+
+- Added [#1386](https://github.com/roboflow/supervision/pull/1386): Support for Transformers v5 functions in [`sv.Detections.from_transformers`](https://supervision.roboflow.com/0.23.0/detection/core/#supervision.detection.core.Detections.from_transformers). This includes the `DetrImageProcessor` methods `post_process_object_detection`, `post_process_panoptic_segmentation`, `post_process_semantic_segmentation`, and `post_process_instance_segmentation`.
+
+```python
+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)
+```
+
+- Added [#1354](https://github.com/roboflow/supervision/pull/1354): Ultralytics SAM (Segment Anything Model) support in [`sv.Detections.from_ultralytics`](https://supervision.roboflow.com/0.23.0/detection/core/#supervision.detection.core.Detections.from_ultralytics). [SAM2](https://sam2.metademolab.com/) was released during this update, and is already supported via [`sv.Detections.from_sam`](https://supervision.roboflow.com/0.23.0/detection/core/#supervision.detection.core.Detections.from_sam).
+
+```python
+import supervision as sv
+from segment_anything import (
+    sam_model_registry,
+    SamAutomaticMaskGenerator
+)
+sam_model_reg = sam_model_registry[MODEL_TYPE]
+sam = sam_model_reg(checkpoint=CHECKPOINT_PATH).to(device=DEVICE)
+mask_generator = SamAutomaticMaskGenerator(sam)
+sam_result = mask_generator.generate(IMAGE)
+detections = sv.Detections.from_sam(sam_result=sam_result)
+```
+
+- Added [#1458](https://github.com/roboflow/supervision/pull/1458): `outline_color` options for [`TriangleAnnotator`](https://supervision.roboflow.com/0.23.0/detection/annotators/#supervision.annotators.core.TriangleAnnotator) and [`DotAnnotator`](https://supervision.roboflow.com/0.23.0/detection/annotators/#supervision.annotators.core.DotAnnotator).
+
+- Added [#1409](https://github.com/roboflow/supervision/pull/1409): `text_color` option for [`VertexLabelAnnotator`](https://supervision.roboflow.com/0.23.0/keypoint/annotators/#supervision.keypoint.annotators.VertexLabelAnnotator) keypoint annotator.
+
+- Changed [#1434](https://github.com/roboflow/supervision/pull/1434): [`InferenceSlicer`](https://supervision.roboflow.com/0.23.0/detection/tools/inference_slicer/) now features an `overlap_wh` parameter, making it easier to compute slice sizes when handling overlapping slices.
+
+- Fix [#1448](https://github.com/roboflow/supervision/pull/1448): Various annotator type issues have been resolved, supporting expanded error handling.
+
+- Fix [#1348](https://github.com/roboflow/supervision/pull/1348): Introduced a new method for [seeking to a specific video frame](https://supervision.roboflow.com/0.23.0/utils/video/#supervision.utils.video.get_video_frames_generator), addressing cases where traditional seek methods were failing. It can be enabled with `iterative_seek=True`.
+
+```python
+import supervision as sv
+
+for frame in sv.get_video_frames_generator(
+    source_path=<SOURCE_VIDEO_PATH>,
+    start=60,
+    iterative_seek=True
+):
+    ...
+```
+
+- Fix [#1424](https://github.com/roboflow/supervision/pull/1424): `plot_image` function now clearly indicates that the size is in inches.
+
+!!! failure "Removed"
+
+    The `track_buffer`, `track_thresh`, and `match_thresh` parameters in [`ByteTrack`](trackers.md/#supervision.tracker.byte_tracker.core.ByteTrack) are deprecated and were removed as of `supervision-0.23.0`. Use `lost_track_buffer,` `track_activation_threshold`, and `minimum_matching_threshold` instead.
+
+!!! failure "Removed"
+
+    The `triggering_position` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) was removed as of `supervision-0.23.0`. Use `triggering_anchors` instead.
+
+!!! failure "Deprecated"
+
+    `overlap_filter_strategy` in `InferenceSlicer.__init__` is deprecated and will be removed in `supervision-0.27.0`. Use `overlap_strategy` instead.
+
+!!! failure "Deprecated"
+
+    `overlap_ratio_wh` in `InferenceSlicer.__init__` is deprecated and will be removed in `supervision-0.27.0`. Use `overlap_wh` instead.
+
 ### 0.22.0 <small>Jul 12, 2024</small>
 
-- Added [#1326](https://github.com/roboflow/supervision/pull/1326): [`sv.DetectionsDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset) and [`sv.ClassificationDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.ClassificationDataset) allowing to load the images into memory only when necessary (lazy loading).
+- Added [#1326](https://github.com/roboflow/supervision/pull/1326): [`sv.DetectionsDataset`](https://supervision.roboflow.com/0.22.0/datasets/core/#supervision.dataset.core.DetectionDataset) and [`sv.ClassificationDataset`](https://supervision.roboflow.com/0.22.0/datasets/core/#supervision.dataset.core.ClassificationDataset) allowing to load the images into memory only when necessary (lazy loading).
 
 !!! failure "Deprecated"
 
@@ -33,15 +306,15 @@ for path, image, annotation in ds_train:
     # loads image on demand
 ```
 
-- Added [#1296](https://github.com/roboflow/supervision/pull/1296): [`sv.Detections.from_lmm`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_lmm) now supports parsing results from the [Florence 2](https://huggingface.co/microsoft/Florence-2-large) model, extending the capability to handle outputs from this Large Multimodal Model (LMM). This includes detailed object detection, OCR with region proposals, segmentation, and more. Find out more in our [Colab notebook](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-finetune-florence-2-on-detection-dataset.ipynb).
+- Added [#1296](https://github.com/roboflow/supervision/pull/1296): [`sv.Detections.from_lmm`](https://supervision.roboflow.com/0.22.0/detection/core/#supervision.detection.core.Detections.from_lmm) now supports parsing results from the [Florence 2](https://huggingface.co/microsoft/Florence-2-large) model, extending the capability to handle outputs from this Large Multimodal Model (LMM). This includes detailed object detection, OCR with region proposals, segmentation, and more. Find out more in our [Colab notebook](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-finetune-florence-2-on-detection-dataset.ipynb).
 
-- Added [#1232](https://github.com/roboflow/supervision/pull/1232) to support keypoint detection with Mediapipe. Both [legacy](https://colab.research.google.com/github/googlesamples/mediapipe/blob/main/examples/pose_landmarker/python/%5BMediaPipe_Python_Tasks%5D_Pose_Landmarker.ipynb) and [modern](https://ai.google.dev/edge/mediapipe/solutions/vision/pose_landmarker/python) pipelines are supported. See [`sv.KeyPoints.from_mediapipe`](https://supervision.roboflow.com/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe) for more.
+- Added [#1232](https://github.com/roboflow/supervision/pull/1232) to support keypoint detection with Mediapipe. Both [legacy](https://colab.research.google.com/github/googlesamples/mediapipe/blob/main/examples/pose_landmarker/python/%5BMediaPipe_Python_Tasks%5D_Pose_Landmarker.ipynb) and [modern](https://ai.google.dev/edge/mediapipe/solutions/vision/pose_landmarker/python) pipelines are supported. See [`sv.KeyPoints.from_mediapipe`](https://supervision.roboflow.com/0.22.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe) for more.
 
-- Added [#1316](https://github.com/roboflow/supervision/pull/1316): [`sv.KeyPoints.from_mediapipe`](https://supervision.roboflow.com/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe) extended to support FaceMesh from Mediapipe. This enhancement allows for processing both face landmarks from `FaceLandmarker`, and legacy results from `FaceMesh`.
+- Added [#1316](https://github.com/roboflow/supervision/pull/1316): [`sv.KeyPoints.from_mediapipe`](https://supervision.roboflow.com/0.22.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe) extended to support FaceMesh from Mediapipe. This enhancement allows for processing both face landmarks from `FaceLandmarker`, and legacy results from `FaceMesh`.
 
-- Added [#1310](https://github.com/roboflow/supervision/pull/1310): [`sv.KeyPoints.from_detectron2`](https://supervision.roboflow.com/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_detectron2) is a new `KeyPoints` method, adding support for extracting keypoints from the popular [Detectron 2](https://github.com/facebookresearch/detectron2) platform.
+- Added [#1310](https://github.com/roboflow/supervision/pull/1310): [`sv.KeyPoints.from_detectron2`](https://supervision.roboflow.com/0.22.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_detectron2) is a new `KeyPoints` method, adding support for extracting keypoints from the popular [Detectron 2](https://github.com/facebookresearch/detectron2) platform.
 
-- Added [#1300](https://github.com/roboflow/supervision/pull/1300): [`sv.Detections.from_detectron2`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_detectron2) now supports segmentation models detectron2. The resulting masks can be used with [`sv.MaskAnnotator`](https://supervision.roboflow.com/latest/annotators/#supervision.annotators.core.MaskAnnotator) for displaying annotations.
+- Added [#1300](https://github.com/roboflow/supervision/pull/1300): [`sv.Detections.from_detectron2`](https://supervision.roboflow.com/0.22.0/detection/core/#supervision.detection.core.Detections.from_detectron2) now supports segmentation models detectron2. The resulting masks can be used with [`sv.MaskAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.MaskAnnotator) for displaying annotations.
 
 ```python
 import supervision as sv
@@ -63,7 +336,7 @@ mask_annotator = sv.MaskAnnotator()
 annotated_frame = mask_annotator.annotate(scene=image.copy(), detections=detections)
 ```
 
-- Added [#1277](https://github.com/roboflow/supervision/pull/1277): if you provide a font that supports symbols of a language, [`sv.RichLabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator.annotate) will draw them on your images.
+- Added [#1277](https://github.com/roboflow/supervision/pull/1277): if you provide a font that supports symbols of a language, [`sv.RichLabelAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.LabelAnnotator.annotate) will draw them on your images.
   - Various other annotators have been revised to ensure proper in-place functionality when used with `numpy` arrays. Additionally, we fixed a bug where `sv.ColorAnnotator` was filling boxes with solid color when used in-place.
 
 ```python
@@ -90,7 +363,7 @@ train_ds = sv.DetectionDataset.from_yolo(
     images_directory_path="/content/dataset/train/images",
     annotations_directory_path="/content/dataset/train/labels",
     data_yaml_path="/content/dataset/data.yaml",
-    is_obb=True
+    is_obb=True,
 )
 
 _, image, detections in train_ds[0]
@@ -99,25 +372,25 @@ obb_annotator = OrientedBoxAnnotator()
 annotated_image = obb_annotator.annotate(scene=image.copy(), detections=detections)
 ```
 
-- Fixed [#1312](https://github.com/roboflow/supervision/pull/1312): Fixed [`CropAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.TraceAnnotator.annotate).
+- Fixed [#1312](https://github.com/roboflow/supervision/pull/1312): Fixed [`CropAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.TraceAnnotator.annotate).
 
 !!! failure "Removed"
 
-    `BoxAnnotator` was removed, however `BoundingBoxAnnotator` has been renamed to `BoxAnnotator`. Use a combination of [`BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) and [`LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator) to simulate old `BoundingBox` behavior.
+    `BoxAnnotator` was removed, however `BoundingBoxAnnotator` has been renamed to `BoxAnnotator`. Use a combination of [`BoxAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.BoxAnnotator) and [`LabelAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.LabelAnnotator) to simulate old `BoundingBox` behavior.
 
 !!! failure "Deprecated"
 
-    The name `BoundingBoxAnnotator` has been deprecated and will be removed in `supervision-0.26.0`. It has been renamed to [`BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator).
+    The name `BoundingBoxAnnotator` has been deprecated and will be removed in `supervision-0.26.0`. It has been renamed to [`BoxAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.BoxAnnotator).
 
 - Added [#975](https://github.com/roboflow/supervision/pull/975) 📝 New Cookbooks: serialize detections into [json](https://github.com/roboflow/supervision/blob/de896189b83a1f9434c0a37dd9192ee00d2a1283/docs/notebooks/serialise-detections-to-json.ipynb) and [csv](https://github.com/roboflow/supervision/blob/de896189b83a1f9434c0a37dd9192ee00d2a1283/docs/notebooks/serialise-detections-to-csv.ipynb).
 
 - Added [#1290](https://github.com/roboflow/supervision/pull/1290): Mostly an internal change, our file utility function now support both `str` and `pathlib` paths.
 
-- Added [#1340](https://github.com/roboflow/supervision/pull/1340): Two new methods for converting between bounding box formats - [`xywh_to_xyxy`](https://supervision.roboflow.com/latest/detection/utils/#supervision.detection.utils.xywh_to_xyxy) and [`xcycwh_to_xyxy`](https://supervision.roboflow.com/latest/detection/utils/#supervision.detection.utils.xcycwh_to_xyxy)
+- Added [#1340](https://github.com/roboflow/supervision/pull/1340): Two new methods for converting between bounding box formats - [`xywh_to_xyxy`](https://supervision.roboflow.com/0.22.0/detection/utils/#supervision.detection.utils.xywh_to_xyxy) and [`xcycwh_to_xyxy`](https://supervision.roboflow.com/0.22.0/detection/utils/#supervision.detection.utils.xcycwh_to_xyxy)
 
 !!! failure "Removed"
 
-    `from_roboflow` method has been removed due to deprecation. Use [from_inference](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_inference) instead.
+    `from_roboflow` method has been removed due to deprecation. Use [from_inference](https://supervision.roboflow.com/0.22.0/detection/core/#supervision.detection.core.Detections.from_inference) instead.
 
 !!! failure "Removed"
 
@@ -141,17 +414,17 @@ annotated_image = obb_annotator.annotate(scene=image.copy(), detections=detectio
 
 !!! failure "Removed"
 
-    `ColorPalette.default()` has been removed due to deprecation. Use [ColorPalette.DEFAULT](https://supervision.roboflow.com/latest/utils/draw/#supervision.draw.color.ColorPalette.DEFAULT) instead.
+    `ColorPalette.default()` has been removed due to deprecation. Use [ColorPalette.DEFAULT](https://supervision.roboflow.com/0.22.0/utils/draw/#supervision.draw.color.ColorPalette.DEFAULT) instead.
 
 !!! failure "Removed"
 
-    `FPSMonitor.__call__` has been removed due to deprecation. Use the attribute [FPSMonitor.fps](https://supervision.roboflow.com/latest/utils/video/#supervision.utils.video.FPSMonitor.fps) instead.
+    `FPSMonitor.__call__` has been removed due to deprecation. Use the attribute [FPSMonitor.fps](https://supervision.roboflow.com/0.22.0/utils/video/#supervision.utils.video.FPSMonitor.fps) instead.
 
 ### 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/latest/detection/core/#supervision.detection.core.Detections.with_nmm) to perform non-maximum merging on the current set of object detections.
+- Added [#500](https://github.com/roboflow/supervision/pull/500): [`sv.Detections.with_nmm`](https://supervision.roboflow.com/0.21.0/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/latest/detection/core/#supervision.detection.core.Detections.from_lmm) allowing to parse Large Multimodal Model (LMM) text result into [`sv.Detections`](https://supervision.roboflow.com/latest/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.
+- Added [#1221](https://github.com/roboflow/supervision/pull/1221): [`sv.Detections.from_lmm`](https://supervision.roboflow.com/0.21.0/detection/core/#supervision.detection.core.Detections.from_lmm) allowing to parse Large Multimodal Model (LMM) text result into [`sv.Detections`](https://supervision.roboflow.com/0.21.0/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
@@ -161,7 +434,7 @@ detections = sv.Detections.from_lmm(
     sv.LMM.PALIGEMMA,
     paligemma_result,
     resolution_wh=(1000, 1000),
-    classes=['cat', 'dog']
+    classes=["cat", "dog"],
 )
 detections.xyxy
 # array([[250., 250., 750., 750.]])
@@ -170,7 +443,7 @@ detections.class_id
 # array([0])
 ```
 
-- Added [#1236](https://github.com/roboflow/supervision/pull/1236): [`sv.VertexLabelAnnotator`](https://supervision.roboflow.com/latest/keypoint/annotators/#supervision.keypoint.annotators.EdgeAnnotator.annotate) allowing to annotate every vertex of a keypoint skeleton with custom text and color.
+- Added [#1236](https://github.com/roboflow/supervision/pull/1236): [`sv.VertexLabelAnnotator`](https://supervision.roboflow.com/0.21.0/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
@@ -188,15 +461,15 @@ annotated_frame = edge_annotator.annotate(
 )
 ```
 
-- 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 [#1147](https://github.com/roboflow/supervision/pull/1147): [`sv.KeyPoints.from_inference`](https://supervision.roboflow.com/0.21.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_inference) allowing to create [`sv.KeyPoints`](https://supervision.roboflow.com/0.21.0/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 [#1138](https://github.com/roboflow/supervision/pull/1138): [`sv.KeyPoints.from_yolo_nas`](https://supervision.roboflow.com/0.21.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_yolo_nas) allowing to create [`sv.KeyPoints`](https://supervision.roboflow.com/0.21.0/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.
+- Added [#1163](https://github.com/roboflow/supervision/pull/1163): [`sv.mask_to_rle`](https://supervision.roboflow.com/0.21.0/datasets/utils/#supervision.dataset.utils.rle_to_mask) and [`sv.rle_to_mask`](https://supervision.roboflow.com/0.21.0/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 [#1236](https://github.com/roboflow/supervision/pull/1236): [`sv.InferenceSlicer`](https://supervision.roboflow.com/0.21.0/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.
+- Changed [#1178](https://github.com/roboflow/supervision/pull/1178): [`sv.InferenceSlicer`](https://supervision.roboflow.com/0.21.0/detection/tools/inference_slicer/) adding instance segmentation model support.
 
 ```python
 import cv2
@@ -223,9 +496,9 @@ 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 [#1228](https://github.com/roboflow/supervision/pull/1228): [`sv.LineZone`](https://supervision.roboflow.com/0.21.0/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.
+- Changed [#1163](https://github.com/roboflow/supervision/pull/1163): [`sv.DetectionDataset.from_coco`](https://supervision.roboflow.com/0.21.0/datasets/core/#supervision.dataset.core.DetectionDataset.from_coco) and [`sv.DetectionDataset.as_coco`](https://supervision.roboflow.com/0.21.0/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>
 
@@ -352,15 +625,15 @@ annotated_frame = crop_annotator.annotate(
 )
 ```
 
-- 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 [#827](https://github.com/roboflow/supervision/pull/827): [`sv.ByteTrack.reset`](/0.19.0/trackers/#supervision.tracker.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.
+- Changed [#787](https://github.com/roboflow/supervision/pull/787): [`sv.ByteTrack`](/0.19.0/trackers/#supervision.tracker.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.
+    The `track_buffer`, `track_thresh`, and `match_thresh` parameters in `sv.ByteTrack` 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.
 
@@ -783,7 +1056,7 @@ array([
 
 - Added [#101](https://github.com/roboflow/supervision/pull/101): ability to extract masks from YOLOv8 result using [`sv.Detections.from_yolov8`](/0.8.0/detection/core/#supervision.detection.core.Detections.from_yolov8). Here is an example illustrating how to extract boolean masks from the result of the YOLOv8 model inference.
 
-- Added [#122](https://github.com/roboflow/supervision/pull/122): ability to crop image using [`sv.crop`](/latest/utils/image/#crop). Here is an example showing how to get a separate crop for each detection in `sv.Detections`.
+- Added [#122](https://github.com/roboflow/supervision/pull/122): ability to crop image using [`sv.crop`](/0.9.0/utils/image/#crop). Here is an example showing how to get a separate crop for each detection in `sv.Detections`.
 
 - Added [#120](https://github.com/roboflow/supervision/pull/120): ability to conveniently save multiple images into directory using [`sv.ImageSink`](/0.9.0/utils/image/#imagesink). Here is an example showing how to save every tenth video frame as a separate image.
 
@@ -795,11 +1068,11 @@ array([
 ...         sink.save_image(image=image)
 ```
 
-- Fixed [#106](https://github.com/roboflow/supervision/issues/106): inconvenient handling of [`sv.PolygonZone`](/0.8.0/supervision/detection/tools/polygon_zone/#polygonzone) coordinates. Now `sv.PolygonZone` accepts coordinates in the form of `[[x1, y1], [x2, y2], ...]` that can be both integers and floats.
+- Fixed [#106](https://github.com/roboflow/supervision/issues/106): inconvenient handling of [`sv.PolygonZone`](/0.8.0/detection/tools/polygon_zone/#polygonzone) coordinates. Now `sv.PolygonZone` accepts coordinates in the form of `[[x1, y1], [x2, y2], ...]` that can be both integers and floats.
 
 ### 0.8.0 <small>May 17, 2023</small>
 
-- Added [#100](https://github.com/roboflow/supervision/pull/100): support for dataset inheritance. The current `Dataset` got renamed to `DetectionDataset`. Now [`DetectionDataset`](/0.8.0/supervision/dataset/core/#detectiondataset) inherits from `BaseDataset`. This change was made to enforce the future consistency of APIs of different types of computer vision datasets.
+- Added [#100](https://github.com/roboflow/supervision/pull/100): support for dataset inheritance. The current `Dataset` got renamed to `DetectionDataset`. Now [`DetectionDataset`](/0.8.0/dataset/core/#detectiondataset) inherits from `BaseDataset`. This change was made to enforce the future consistency of APIs of different types of computer vision datasets.
 - Added [#100](https://github.com/roboflow/supervision/pull/100): ability to save datasets in YOLO format using [`DetectionDataset.as_yolo`](/0.8.0/dataset/core/#supervision.dataset.core.DetectionDataset.as_yolo).
 
 ```python

docs/datasets/core.md

@@ -1,12 +1,10 @@
 ---
 comments: true
-status: new
 ---
 
 # Datasets
 
 !!! warning
-
     Dataset API is still fluid and may change. If you use Dataset API in your project until further notice, freeze the
     `supervision` version in your `requirements.txt` or `setup.py`.
 

docs/deprecated.md

@@ -7,21 +7,36 @@ status: deprecated
 
 These features are phased out due to better alternatives or potential issues in future versions. Deprecated functionalities are supported for **five subsequent releases**, providing time for users to transition to updated methods.
 
-- 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) 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) will be removed in `supervision-0.24.0`.
-- Constructing `DetectionDataset` and `ClassificationDataset` with parameter `images` as `Dict[str, np.ndarray]` will be removed in `supervision-0.26.0`. Please pass a list of paths `List[str]` instead.
+- Constructing [`DetectionDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset) and [`ClassificationDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.ClassificationDataset) with parameter `images` as `Dict[str, np.ndarray]` will be removed in `supervision-0.26.0`. Please pass a list of paths `List[str]` instead.
+
 - The `DetectionDataset.images` property will be removed in `supervision-0.26.0`. Please loop over images with `for path, image, annotation in dataset:`, as that does not require loading all images into memory.
-- `BoundingBoxAnnotator` has been renamed to `BoxAnnotator` after the old implementation of `BoxAnnotator` has been removed. `BoundingBoxAnnotator` will be removed in `supervision-0.26.0`.
+
+- `BoundingBoxAnnotator` has been renamed to `BoxAnnotator` after the old implementation of [`BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) has been removed. `BoundingBoxAnnotator` will be removed in `supervision-0.26.0`.
+
+- `overlap_filter_strategy` in [`InferenceSlicer.__init__`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/) is deprecated and will be removed in `supervision-0.27.0`. Use `overlap_strategy` instead.
+
+- `overlap_ratio_wh` in [`InferenceSlicer.__init__`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/) is deprecated and will be removed in `supervision-0.27.0`. Use `overlap_wh` instead.
 
 # Removed
 
-- [`Detections.from_froboflow`](detection/core.md/#supervision.detection.core.Detections.from_roboflow) is removed as of `supervision-0.22.0`. Use [`Detections.from_inference`](detection/core.md/#supervision.detection.core.Detections.from_inference) instead.
+### 0.24.0
+
+- The `frame_resolution_wh ` parameter in [`sv.PolygonZone`](detection/tools/polygon_zone.md/#supervision.detection.tools.polygon_zone.PolygonZone) has been removed.
+- Supervision installation methods `"headless"` and `"desktop"` were removed, as they are no longer needed. `pip install supervision[headless]` will install the base library and harmlessly warn of non-existent extras.
+
+### 0.23.0
+
+- The `track_buffer`, `track_thresh`, and `match_thresh` parameters in [`ByteTrack`](trackers.md/#supervision.tracker.byte_tracker.core.ByteTrack) are deprecated and were removed as of `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) was removed as of `supervision-0.23.0`. Use `triggering_anchors` instead.
+
+### 0.22.0
+
+- `Detections.from_roboflow` is removed as of `supervision-0.22.0`. Use [`Detections.from_inference`](detection/core.md/#supervision.detection.core.Detections.from_inference) instead.
 - The method `Color.white()` was removed as of `supervision-0.22.0`. Use the constant `Color.WHITE` instead.
 - The method `Color.black()` was removed as of `supervision-0.22.0`. Use the constant `Color.BLACK` instead.
 - The method `Color.red()` was removed as of `supervision-0.22.0`. Use the constant `Color.RED` instead.
 - The method `Color.green()` was removed as of `supervision-0.22.0`. Use the constant `Color.GREEN` instead.
 - The method `Color.blue()` was removed as of `supervision-0.22.0`. Use the constant `Color.BLUE` instead.
-- The method [`ColorPalette.default()`](draw/color.md/#supervision.draw.color.ColorPalette.default) was removed as of `supervision-0.22.0`. Use the constant [`ColorPalette.DEFAULT`](draw/color.md/#supervision.draw.color.ColorPalette.DEFAULT) instead.
+- The method `ColorPalette.default()` was removed as of `supervision-0.22.0`. Use the constant [`ColorPalette.DEFAULT`](/utils/draw/#supervision.draw.color.ColorPalette.DEFAULT) instead.
 - `BoxAnnotator` was removed as of `supervision-0.22.0`, however `BoundingBoxAnnotator` was immediately renamed to `BoxAnnotator`. Use [`BoxAnnotator`](detection/annotators.md/#supervision.annotators.core.BoxAnnotator) and [`LabelAnnotator`](detection/annotators.md/#supervision.annotators.core.LabelAnnotator) instead of the old `BoxAnnotator`.
-- The method [`FPSMonitor.__call__`](utils/video.md/#supervision.utils.video.FPSMonitor.__call__) was removed as of `supervision-0.22.0`. Use the attribute [`FPSMonitor.fps`](utils/video.md/#supervision.utils.video.FPSMonitor.fps) instead.
+- The method `FPSMonitor.__call__` was removed as of `supervision-0.22.0`. Use the attribute [`FPSMonitor.fps`](utils/video.md/#supervision.utils.video.FPSMonitor.fps) instead.

docs/detection/annotators.md

@@ -5,6 +5,8 @@ status: new
 
 # Annotators
 
+Annotators accept detections and apply box or mask visualizations to the detections. Annotators have many available styles.
+
 === "Box"
 
     ```python
@@ -303,7 +305,7 @@ status: new
         font_path="<TTF_FONT_PATH>",
         text_position=sv.Position.CENTER
     )
-    annotated_frame = label_annotator.annotate(
+    annotated_frame = rich_label_annotator.annotate(
         scene=image.copy(),
         detections=detections,
         labels=labels
@@ -316,6 +318,33 @@ status: new
 
     </div>
 
+=== "Icon"
+
+    ```python
+    import supervision as sv
+
+    image = ...
+    detections = sv.Detections(...)
+
+    icon_paths = [
+        "<ICON_PATH>"
+        for _ in detections
+    ]
+
+    icon_annotator = sv.IconAnnotator()
+    annotated_frame = icon_annotator.annotate(
+        scene=image.copy(),
+        detections=detections,
+        icon_path=icon_paths
+    )
+    ```
+
+    <div class="result" markdown>
+
+    ![icon-annotator-example](https://media.roboflow.com/supervision-annotator-examples/icon-annotator-example.png){ align=center width="800" }
+
+    </div>
+
 === "Crop"
 
     ```python
@@ -384,7 +413,7 @@ status: new
     trace_annotator = sv.TraceAnnotator()
 
     video_info = sv.VideoInfo.from_video_path(video_path='...')
-    frames_generator = get_video_frames_generator(source_path='...')
+    frames_generator = sv.get_video_frames_generator(source_path='...')
     tracker = sv.ByteTrack()
 
     with sv.VideoSink(target_path='...', video_info=video_info) as sink:
@@ -415,7 +444,7 @@ status: new
     heat_map_annotator = sv.HeatMapAnnotator()
 
     video_info = sv.VideoInfo.from_video_path(video_path='...')
-    frames_generator = get_video_frames_generator(source_path='...')
+    frames_generator = sv.get_video_frames_generator(source_path='...')
 
     with sv.VideoSink(target_path='...', video_info=video_info) as sink:
         for frame in frames_generator:
@@ -433,6 +462,34 @@ status: new
 
     </div>
 
+=== "Background Color"
+
+    ```python
+    import supervision as sv
+
+    image = ...
+    detections = sv.Detections(...)
+
+    background_overlay_annotator = sv.BackgroundOverlayAnnotator()
+    annotated_frame = background_overlay_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
+    ```
+
+    <div class="result" markdown>
+
+    ![background-overlay-annotator-example](https://media.roboflow.com/supervision-annotator-examples/background-color-annotator-example-purple.png)
+
+    </div>
+
+<div class="md-typeset">
+    <h2>Try Supervision Annotators on your own image</h2>
+    Visualize annotators on images with COCO classes such as people, vehicles, animals, household items.
+</div>
+
+<div style="height: 400px; width: 100%; border-radius: 8px; overflow: hidden;"><iframe src="https://app.roboflow.com/workflows/embed/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3b3JrZmxvd0lkIjoiNDdtd2xuWW16S25VNWtOYUZjMG8iLCJ3b3Jrc3BhY2VJZCI6ImtyT1RBYm5jRmhvUU1DZExPbGU0IiwidXNlcklkIjoiRVJNUFBZY3FQMmZWWjB1NkRpNXZaYXJDdlZPMiIsImlhdCI6MTcyNjgzOTM2N30.gj2F6SnmmURAScJe4PTC1raUXsAK5mZyrUIGIJ44NhM?hideToolbar=true&hideHeader=true&defaultVisual=true" loading="lazy" title="Roboflow Workflow for Supervision Annotators" style="width: 100%; height: 100%; min-height: 400px; border: none;"></iframe></div>
+
 <div class="md-typeset">
     <h2><a href="#supervision.annotators.core.BoxAnnotator">BoxAnnotator</a></h2>
 </div>
@@ -529,6 +586,12 @@ status: new
 
 :::supervision.annotators.core.RichLabelAnnotator
 
+<div class="md-typeset">
+    <h2><a href="#supervision.annotators.core.IconAnnotator">IconAnnotator</a></h2>
+</div>
+
+:::supervision.annotators.core.IconAnnotator
+
 <div class="md-typeset">
     <h2><a href="#supervision.annotators.core.BlurAnnotator">BlurAnnotator</a></h2>
 </div>
@@ -553,6 +616,12 @@ status: new
 
 :::supervision.annotators.core.CropAnnotator
 
+<div class="md-typeset">
+    <h2><a href="#supervision.annotators.core.BackgroundOverlayAnnotator">BackgroundOverlayAnnotator</a></h2>
+</div>
+
+:::supervision.annotators.core.BackgroundOverlayAnnotator
+
 <div class="md-typeset">
     <h2><a href="#supervision.annotators.core.ColorLookup">ColorLookup</a></h2>
 </div>

docs/detection/metrics.md

@@ -2,7 +2,10 @@
 comments: true
 ---
 
-# Metrics
+# Legacy Metrics
+
+Starting with `0.23.0`, a new metrics module is being introduced to supervision.
+Metrics here are part of the legacy evaluation API and will be deprecated in the future.
 
 <div class="md-typeset">
     <h2><a href="#supervision.metrics.detection.ConfusionMatrix">ConfusionMatrix</a></h2>

docs/detection/tools/inference_slicer.md

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

docs/detection/tools/line_zone.md

@@ -1,5 +1,6 @@
 ---
 comments: true
+status: new
 ---
 
 <div class="md-typeset">
@@ -13,3 +14,9 @@ comments: true
 </div>
 
 :::supervision.detection.line_zone.LineZoneAnnotator
+
+<div class="md-typeset">
+  <h2>LineZoneAnnotatorMulticlass</h2>
+</div>
+
+:::supervision.detection.line_zone.LineZoneAnnotatorMulticlass

docs/detection/tools/polygon_zone.md

@@ -1,5 +1,6 @@
 ---
 comments: true
+status: new
 ---
 
 <div class="md-typeset">

docs/detection/utils.md

@@ -17,6 +17,12 @@ status: new
 
 :::supervision.detection.utils.mask_iou_batch
 
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.oriented_box_iou_batch">oriented_box_iou_batch</a></h2>
+</div>
+
+:::supervision.detection.utils.oriented_box_iou_batch
+
 <div class="md-typeset">
   <h2><a href="#supervision.detection.utils.polygon_to_mask">polygon_to_mask</a></h2>
 </div>
@@ -78,19 +84,19 @@ status: new
 :::supervision.detection.utils.pad_boxes
 
 <div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.contains_holes">contains_holes</a></h2>
+  <h2><a href="#supervision.detection.utils.xywh_to_xyxy">xywh_to_xyxy</a></h2>
 </div>
 
 :::supervision.detection.utils.xywh_to_xyxy
 
 <div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.xywh_to_xyxy">xywh_to_xyxy</a></h2>
+  <h2><a href="#supervision.detection.utils.xcycwh_to_xyxy">xcycwh_to_xyxy</a></h2>
 </div>
 
 :::supervision.detection.utils.xcycwh_to_xyxy
 
 <div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.xcycwh_to_xyxy">xcycwh_to_xyxy</a></h2>
+  <h2><a href="#supervision.detection.utils.contains_holes">contains_holes</a></h2>
 </div>
 
 :::supervision.detection.utils.contains_holes

docs/how_to/detect_and_annotate.md

@@ -6,7 +6,7 @@ comments: true
 
 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),
+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
@@ -20,7 +20,6 @@ First, you'll need to obtain predictions from your object detection or segmentat
 model.
 
 === "Inference"
-
     ```python
     import cv2
     from inference import get_model
@@ -31,7 +30,6 @@ model.
     ```
 
 === "Ultralytics"
-
     ```python
     import cv2
     from ultralytics import YOLO
@@ -42,7 +40,6 @@ model.
     ```
 
 === "Transformers"
-
     ```python
     import torch
     from PIL import Image
@@ -68,8 +65,7 @@ model.
 Now that we have predictions from a model, we can load them into Supervision.
 
 === "Inference"
-
-    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.
+    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.
 
     ```{ .py hl_lines="2 8" }
     import cv2
@@ -83,8 +79,7 @@ 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`](detection/core/#supervision.detection.core.Detections.from_ultralytics) method, which accepts model results from both detection and segmentation models.
+    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.
 
     ```{ .py hl_lines="2 8" }
     import cv2
@@ -98,8 +93,7 @@ Now that we have predictions from a model, we can load them into Supervision.
     ```
 
 === "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.
+    We can do so using the [`sv.Detections.from_transformers`](/latest/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
@@ -135,10 +129,9 @@ You can load predictions from other computer vision frameworks and libraries usi
 
 ## 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.BoxAnnotator`](/latest/annotators/#supervision.annotators.core.BoxAnnotator) and [`sv.LabelAnnotator`](/latest/annotators/#supervision.annotators.core.LabelAnnotator) classes.
+Finally, we can annotate the image with the predictions. Since we are working with an object detection model, we will use the [`sv.BoxAnnotator`](/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) and [`sv.LabelAnnotator`](/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator) classes.
 
 === "Inference"
-
     ```{ .py hl_lines="10-16" }
     import cv2
     import supervision as sv
@@ -159,7 +152,6 @@ Finally, we can annotate the image with the predictions. Since we are working wi
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="10-16" }
     import cv2
     import supervision as sv
@@ -180,7 +172,6 @@ Finally, we can annotate the image with the predictions. Since we are working wi
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="23-30" }
     import torch
     import supervision as sv
@@ -217,12 +208,11 @@ Finally, we can annotate the image with the predictions. Since we are working wi
 
 ## Display Custom Labels
 
-By default, [`sv.LabelAnnotator`](/latest/annotators/#supervision.annotators.core.LabelAnnotator)
+By default, [`sv.LabelAnnotator`](/latest/detection/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
@@ -249,7 +239,6 @@ override this behavior by passing a list of custom `labels` to the `annotate` me
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="13-17 22" }
     import cv2
     import supervision as sv
@@ -276,7 +265,6 @@ override this behavior by passing a list of custom `labels` to the `annotate` me
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="26-30 35" }
     import torch
     import supervision as sv
@@ -320,13 +308,12 @@ override this behavior by passing a list of custom `labels` to the `annotate` me
 ## Annotate Image with Segmentations
 
 If you are running the segmentation model
-[`sv.MaskAnnotator`](/latest/annotators/#supervision.annotators.core.MaskAnnotator)
+[`sv.MaskAnnotator`](/latest/detection/annotators/#supervision.annotators.core.MaskAnnotator)
 is a drop-in replacement for
-[`sv.BoxAnnotator`](/latest/annotators/#supervision.annotators.core.BoxAnnotator)
+[`sv.BoxAnnotator`](/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator)
 that will allow you to draw masks instead of boxes.
 
 === "Inference"
-
     ```python
     import cv2
     import supervision as sv
@@ -347,7 +334,6 @@ that will allow you to draw masks instead of boxes.
     ```
 
 === "Ultralytics"
-
     ```python
     import cv2
     import supervision as sv
@@ -368,7 +354,6 @@ that will allow you to draw masks instead of boxes.
     ```
 
 === "Transformers"
-
     ```python
     import torch
     import supervision as sv

docs/how_to/detect_small_objects.md

@@ -20,7 +20,6 @@ Small object detection in high-resolution images presents challenges due to the
 size relative to the image resolution.
 
 === "Inference"
-
     ```python
     import cv2
     import supervision as sv
@@ -41,7 +40,6 @@ size relative to the image resolution.
     ```
 
 === "Ultralytics"
-
     ```python
     import cv2
     import supervision as sv
@@ -62,7 +60,6 @@ size relative to the image resolution.
     ```
 
 === "Transformers"
-
     ```python
     import torch
     import supervision as sv
@@ -108,7 +105,6 @@ identification at the cost of processing speed and increased memory usage. This
 is less effective for ultra-high-resolution images (4K and above).
 
 === "Inference"
-
     ```{ .py hl_lines="5" }
     import cv2
     import supervision as sv
@@ -129,7 +125,6 @@ is less effective for ultra-high-resolution images (4K and above).
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="7" }
     import cv2
     import supervision as sv
@@ -162,7 +157,6 @@ objects within each, and aggregating the results.
 </video>
 
 === "Inference"
-
     ```{ .py hl_lines="9-14" }
     import cv2
     import numpy as np
@@ -189,7 +183,6 @@ objects within each, and aggregating the results.
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="9-14" }
     import cv2
     import numpy as np
@@ -216,7 +209,6 @@ objects within each, and aggregating the results.
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="13-28" }
     import cv2
     import torch
@@ -269,7 +261,6 @@ objects within each, and aggregating the results.
 [`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
@@ -296,7 +287,6 @@ objects within each, and aggregating the results.
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="6 16 19-20" }
     import cv2
     import numpy as np

docs/how_to/filter_detections.md

@@ -15,7 +15,6 @@ the filters in their applications.
 Allows you to select detections that belong only to one selected class.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -30,7 +29,6 @@ Allows you to select detections that belong only to one selected class.
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -49,7 +47,6 @@ Allows you to select detections that belong only to one selected class.
 Allows you to select detections that belong only to selected set of classes.
 
 === "After"
-
     ```python
     import numpy as np
     import supervision as sv
@@ -66,7 +63,6 @@ Allows you to select detections that belong only to selected set of classes.
     </div>
 
 === "Before"
-
     ```python
     import numpy as np
     import supervision as sv
@@ -87,7 +83,6 @@ Allows you to select detections that belong only to selected set of classes.
 Allows you to select detections with specific confidence value, for example higher than selected threshold.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -102,7 +97,6 @@ Allows you to select detections with specific confidence value, for example high
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -122,7 +116,6 @@ Allows you to select detections based on their size. We define the area as the n
 detection in the image. In the example below, we have sifted out the detections that are too small.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -137,7 +130,6 @@ detection in the image. In the example below, we have sifted out the detections
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -159,7 +151,6 @@ but small on a 3840x2160 image. In such cases, we can filter out detections base
 occupied by them. In the example below, we remove too large detections.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -178,7 +169,6 @@ occupied by them. In the example below, we remove too large detections.
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -203,7 +193,6 @@ can be criteria for rejecting detection. Implementing such filtering requires a
 simple and fast.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -220,7 +209,6 @@ simple and fast.
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -242,7 +230,6 @@ Allows you to use `Detections` in combination with `PolygonZone` to weed out bou
 zone. In the example below you can see how to filter out all detections located in the lower part of the image.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -259,7 +246,6 @@ zone. In the example below you can see how to filter out all detections located
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 
@@ -280,7 +266,6 @@ zone. In the example below you can see how to filter out all detections located
 `Detections`' greatest strength, however, is that you can build arbitrarily complex logical conditions by simply combining separate conditions using `&` or `|`.
 
 === "After"
-
     ```python
     import supervision as sv
 
@@ -297,7 +282,6 @@ zone. In the example below you can see how to filter out all detections located
     </div>
 
 === "Before"
-
     ```python
     import supervision as sv
 

docs/how_to/process_datasets.md

@@ -0,0 +1,454 @@
+---
+comments: true
+---
+
+With Supervision, you can load and manipulate classification, object detection, and
+segmentation datasets. This tutorial will walk you through how to load, split, merge,
+visualize, and augment datasets in Supervision.
+
+## Download Dataset
+
+In this tutorial, we will use a dataset from
+[Roboflow Universe](https://universe.roboflow.com/), a public repository of
+thousands of computer vision datasets. If you already have your dataset in
+[COCO](https://roboflow.com/formats/coco-json),
+[YOLO](https://roboflow.com/formats/yolov8-pytorch-txt),
+or [Pascal VOC](https://roboflow.com/formats/pascal-voc-xml) format, you can skip this
+section.
+
+```bash
+pip install roboflow
+```
+
+Next, log into your Roboflow account and download the dataset of your choice in the
+COCO, YOLO, or Pascal VOC format. You can customize the following code snippet with
+your workspace ID, project ID, and version number.
+
+=== "COCO"
+
+    ```python
+    import roboflow
+
+    roboflow.login()
+
+    rf = roboflow.Roboflow()
+    project = rf.workspace('<WORKSPACE_ID>').project('<PROJECT_ID>')
+    dataset = project.version('<PROJECT_VERSION>').download("coco")
+    ```
+
+=== "YOLO"
+
+    ```python
+    import roboflow
+
+    roboflow.login()
+
+    rf = roboflow.Roboflow()
+    project = rf.workspace('<WORKSPACE_ID>').project('<PROJECT_ID>')
+    dataset = project.version('<PROJECT_VERSION>').download("yolov8")
+    ```
+
+=== "Pascal VOC"
+
+    ```python
+    import roboflow
+
+    roboflow.login()
+
+    rf = roboflow.Roboflow()
+    project = rf.workspace('<WORKSPACE_ID>').project('<PROJECT_ID>')
+    dataset = project.version('<PROJECT_VERSION>').download("voc")
+    ```
+
+## Load Dataset
+
+The Supervision library provides convenient functions to load datasets in various
+formats. If your dataset is already split into train, test, and valid subsets, you can
+load each of those as separate [`sv.DetectionDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset)
+instances.
+
+=== "COCO"
+
+    We can do so using the [`sv.DetectionDataset.from_coco`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.from_coco) to load annotations in [COCO](https://roboflow.com/formats/coco-json) format.
+
+    ```python
+    import supervision as sv
+
+    ds_train = sv.DetectionDataset.from_coco(
+        images_directory_path=f'{dataset.location}/train',
+        annotations_path=f'{dataset.location}/train/_annotations.coco.json',
+    )
+    ds_valid = sv.DetectionDataset.from_coco(
+        images_directory_path=f'{dataset.location}/valid',
+        annotations_path=f'{dataset.location}/valid/_annotations.coco.json',
+    )
+    ds_test = sv.DetectionDataset.from_coco(
+        images_directory_path=f'{dataset.location}/test',
+        annotations_path=f'{dataset.location}/test/_annotations.coco.json',
+    )
+
+    ds_train.classes
+    # ['person', 'bicycle', 'car', ...]
+
+    len(ds_train), len(ds_valid), len(ds_test)
+    # 800, 100, 100
+    ```
+
+=== "YOLO"
+
+    We can do so using the [`sv.DetectionDataset.from_yolo`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.from_yolo) to load annotations in [YOLO](https://roboflow.com/formats/yolov8-pytorch-txt) format.
+
+    ```python
+    import supervision as sv
+
+    ds_train = sv.DetectionDataset.from_yolo(
+        images_directory_path=f'{dataset.location}/train/images',
+        annotations_directory_path=f'{dataset.location}/train/labels',
+        data_yaml_path=f'{dataset.location}/data.yaml'
+    )
+    ds_valid = sv.DetectionDataset.from_yolo(
+        images_directory_path=f'{dataset.location}/valid/images',
+        annotations_directory_path=f'{dataset.location}/valid/labels',
+        data_yaml_path=f'{dataset.location}/data.yaml'
+    )
+    ds_test = sv.DetectionDataset.from_yolo(
+        images_directory_path=f'{dataset.location}/test/images',
+        annotations_directory_path=f'{dataset.location}/test/labels',
+        data_yaml_path=f'{dataset.location}/data.yaml'
+    )
+
+    ds_train.classes
+    # ['person', 'bicycle', 'car', ...]
+
+    len(ds_train), len(ds_valid), len(ds_test)
+    # 800, 100, 100
+    ```
+
+=== "Pascal VOC"
+
+    We can do so using the [`sv.DetectionDataset.from_pascal_voc`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.from_pascal_voc) to load annotations in [Pascal VOC](https://roboflow.com/formats/pascal-voc-xml) format.
+
+    ```python
+    import supervision as sv
+
+    ds_train = sv.DetectionDataset.from_pascal_voc(
+        images_directory_path=f'{dataset.location}/train/images',
+        annotations_directory_path=f'{dataset.location}/train/labels'
+    )
+    ds_valid = sv.DetectionDataset.from_pascal_voc(
+        images_directory_path=f'{dataset.location}/valid/images',
+        annotations_directory_path=f'{dataset.location}/valid/labels'
+    )
+    ds_test = sv.DetectionDataset.from_pascal_voc(
+        images_directory_path=f'{dataset.location}/test/images',
+        annotations_directory_path=f'{dataset.location}/test/labels'
+    )
+
+    ds_train.classes
+    # ['person', 'bicycle', 'car', ...]
+
+    len(ds_train), len(ds_valid), len(ds_test)
+    # 800, 100, 100
+    ```
+
+## Split Dataset
+
+If your dataset is not already split into train, test, and valid subsets, you can
+easily do so using the [`sv.DetectionDataset.split`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.split)
+method. We can split it as follows, ensuring a random shuffle of the data.
+
+```python
+import supervision as sv
+
+ds = sv.DetectionDataset(...)
+
+len(ds)
+# 1000
+
+ds_train, ds = ds.split(split_ratio=0.8, shuffle=True)
+ds_valid, ds_test = ds.split(split_ratio=0.5, shuffle=True)
+
+len(ds_train), len(ds_valid), len(ds_test)
+# 800, 100, 100
+```
+
+## Merge Dataset
+
+If you have multiple datasets that you would like to merge, you can do so using the
+[`sv.DetectionDataset.merge`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.merge)
+method.
+
+=== "COCO"
+
+    ```{ .py hl_lines="22-28" }
+    import supervision as sv
+
+    ds_train = sv.DetectionDataset.from_coco(
+        images_directory_path=f'{dataset.location}/train',
+        annotations_path=f'{dataset.location}/train/_annotations.coco.json',
+    )
+    ds_valid = sv.DetectionDataset.from_coco(
+        images_directory_path=f'{dataset.location}/valid',
+        annotations_path=f'{dataset.location}/valid/_annotations.coco.json',
+    )
+    ds_test = sv.DetectionDataset.from_coco(
+        images_directory_path=f'{dataset.location}/test',
+        annotations_path=f'{dataset.location}/test/_annotations.coco.json',
+    )
+
+    ds_train.classes
+    # ['person', 'bicycle', 'car', ...]
+
+    len(ds_train), len(ds_valid), len(ds_test)
+    # 800, 100, 100
+
+    ds = sv.DetectionDataset.merge([ds_train, ds_valid, ds_test])
+
+    ds.classes
+    # ['person', 'bicycle', 'car', ...]
+
+    len(ds)
+    # 1000
+    ```
+
+=== "YOLO"
+
+    ```{ .py hl_lines="25-31" }
+    import supervision as sv
+
+    ds_train = sv.DetectionDataset.from_yolo(
+        images_directory_path=f'{dataset.location}/train/images',
+        annotations_directory_path=f'{dataset.location}/train/labels',
+        data_yaml_path=f'{dataset.location}/data.yaml'
+    )
+    ds_valid = sv.DetectionDataset.from_yolo(
+        images_directory_path=f'{dataset.location}/valid/images',
+        annotations_directory_path=f'{dataset.location}/valid/labels',
+        data_yaml_path=f'{dataset.location}/data.yaml'
+    )
+    ds_test = sv.DetectionDataset.from_yolo(
+        images_directory_path=f'{dataset.location}/test/images',
+        annotations_directory_path=f'{dataset.location}/test/labels',
+        data_yaml_path=f'{dataset.location}/data.yaml'
+    )
+
+    ds_train.classes
+    # ['person', 'bicycle', 'car', ...]
+
+    len(ds_train), len(ds_valid), len(ds_test)
+    # 800, 100, 100
+
+    ds = sv.DetectionDataset.merge([ds_train, ds_valid, ds_test])
+
+    ds.classes
+    # ['person', 'bicycle', 'car', ...]
+
+    len(ds)
+    # 1000
+    ```
+
+=== "Pascal VOC"
+
+    ```{ .py hl_lines="22-28" }
+    import supervision as sv
+
+    ds_train = sv.DetectionDataset.from_pascal_voc(
+        images_directory_path=f'{dataset.location}/train/images',
+        annotations_directory_path=f'{dataset.location}/train/labels'
+    )
+    ds_valid = sv.DetectionDataset.from_pascal_voc(
+        images_directory_path=f'{dataset.location}/valid/images',
+        annotations_directory_path=f'{dataset.location}/valid/labels'
+    )
+    ds_test = sv.DetectionDataset.from_pascal_voc(
+        images_directory_path=f'{dataset.location}/test/images',
+        annotations_directory_path=f'{dataset.location}/test/labels'
+    )
+
+    ds_train.classes
+    # ['person', 'bicycle', 'car', ...]
+
+    len(ds_train), len(ds_valid), len(ds_test)
+    # 800, 100, 100
+
+    ds = sv.DetectionDataset.merge([ds_train, ds_valid, ds_test])
+
+    ds.classes
+    # ['person', 'bicycle', 'car', ...]
+
+    len(ds)
+    # 1000
+    ```
+
+## Iterate over Dataset
+
+There are two ways to loop over a `sv.DetectionDataset`: using a direct
+[for loop](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.__iter__)
+called on the `sv.DetectionDataset` instance or loading `sv.DetectionDataset` entries
+[by index](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.__getitem__).
+
+```python
+import supervision as sv
+
+ds = sv.DetectionDataset(...)
+
+# Option 1
+for image_path, image, annotations in ds:
+    ... # Process each image and its annotations
+
+# Option 2
+for idx in range(len(ds)):
+    image_path, image, annotations = ds[idx]
+    ... # Process the image and annotations at index `idx`
+```
+
+## Visualize Dataset
+
+The Supervision library provides tools for easily visualizing your detection dataset.
+You can create a grid of annotated images to quickly inspect your data and labels.
+First, initialize the [`sv.BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator)
+and [`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator).
+Then, iterate through a subset of the dataset (e.g., the first 25 images), drawing
+bounding boxes and class labels on each image. Finally, combine the annotated images
+into a grid for display.
+
+```python
+import supervision as sv
+
+ds = sv.DetectionDataset(...)
+
+box_annotator = sv.BoxAnnotator()
+label_annotator = sv.LabelAnnotator()
+
+annotated_images = []
+for i in range(16):
+    _, image, annotations = ds[i]
+
+    labels = [ds.classes[class_id] for class_id in annotations.class_id]
+
+    annotated_image = image.copy()
+    annotated_image = box_annotator.annotate(annotated_image, annotations)
+    annotated_image = label_annotator.annotate(annotated_image, annotations, labels)
+    annotated_images.append(annotated_image)
+
+grid = sv.create_tiles(
+    annotated_images,
+    grid_size=(4, 4),
+    single_tile_size=(400, 400),
+    tile_padding_color=sv.Color.WHITE,
+    tile_margin_color=sv.Color.WHITE
+)
+```
+
+![visualize-dataset](https://media.roboflow.com/supervision-docs/visualize-dataset.png)
+
+## Save Dataset
+
+=== "COCO"
+
+    We can do so using the [`sv.DetectionDataset.as_coco`](https://supervision.roboflow.com/datasets/#supervision.dataset.core.DetectionDataset.as_coco) method to save annotations in [COCO](https://roboflow.com/formats/coco-json) format.
+
+    ```python
+    import supervision as sv
+
+    ds = sv.DetectionDataset(...)
+
+    ds.as_coco(
+        images_directory_path='<IMAGE_DIRECTORY_PATH>',
+        annotations_path='<ANNOTATIONS_PATH>'
+    )
+    ```
+
+=== "YOLO"
+
+    We can do so using the [`sv.DetectionDataset.as_yolo`](https://supervision.roboflow.com/datasets/#supervision.dataset.core.DetectionDataset.as_yolo) method to save annotations in [YOLO](https://roboflow.com/formats/yolov8-pytorch-txt) format.
+
+    ```python
+    import supervision as sv
+
+    ds = sv.DetectionDataset(...)
+
+    ds.as_yolo(
+        images_directory_path='<IMAGE_DIRECTORY_PATH>',
+        annotations_directory_path='<ANNOTATIONS_DIRECTORY_PATH>',
+        data_yaml_path='<DATA_YAML_PATH>'
+    )
+    ```
+
+=== "Pascal VOC"
+
+    We can do so using the [`sv.DetectionDataset.as_pascal_voc`](https://supervision.roboflow.com/datasets/#supervision.dataset.core.DetectionDataset.as_pascal_voc) method to save annotations in [Pascal VOC](https://roboflow.com/formats/pascal-voc-xml) format.
+
+    ```python
+    import supervision as sv
+
+    ds = sv.DetectionDataset(...)
+
+    ds.as_pascal_voc(
+        images_directory_path='<IMAGE_DIRECTORY_PATH>',
+        annotations_directory_path='<ANNOTATIONS_DIRECTORY_PATH>'
+    )
+    ```
+
+## Augment Dataset
+
+In this section, we'll explore using Supervision in combination with Albumentations to
+augment our dataset. Data augmentation is a common technique in computer vision to
+increase the size and diversity of training datasets, leading to improved model
+performance and generalization.
+
+```bash
+pip install augmentation
+```
+
+Albumentations provides a flexible and powerful API for image augmentation. The core of
+the library is the [`Compose`](https://albumentations.ai/docs/api_reference/full_reference/?h=compose#albumentations.core.composition.Compose)
+class, which allows you to chain multiple image transformations together. Each
+transformation is defined using a dedicated class, such as
+[`HorizontalFlip`](https://albumentations.ai/docs/api_reference/full_reference/?h=horizontalflip#albumentations.augmentations.geometric.transforms.HorizontalFlip),
+[`RandomBrightnessContrast`](https://albumentations.ai/docs/api_reference/full_reference/?h=horizontalflip#albumentations.augmentations.transforms.RandomBrightnessContrast),
+or [`Perspective`](https://albumentations.ai/docs/api_reference/full_reference/?h=horizontalflip#albumentations.augmentations.geometric.transforms.Perspective).
+
+```python
+import albumentations as A
+
+augmentation = A.Compose(
+    transforms=[
+        A.Perspective(p=0.1),
+        A.HorizontalFlip(p=0.5),
+        A.RandomBrightnessContrast(p=0.5)
+    ],
+    bbox_params=A.BboxParams(
+        format='pascal_voc',
+        label_fields=['category']
+    ),
+)
+```
+
+The key is to set `format='pascal_voc'`, which corresponds to the
+`[x_min, y_min, x_max, y_max]` bounding box format used in Supervision.
+
+```python
+import numpy as np
+import supervision as sv
+from dataclasses import replace
+
+ds = sv.DetectionDataset(...)
+
+_, original_image, original_annotations = ds[0]
+
+output = augmentation(
+    image=original_image,
+    bboxes=original_annotations.xyxy,
+    category=original_annotations.class_id
+)
+
+augmented_image = output['image']
+augmented_annotations = replace(
+    original_annotations,
+    xyxy=np.array(output['bboxes']),
+    class_id=np.array(output['category'])
+)
+```
+
+![augment-dataset](https://media.roboflow.com/supervision-docs/augment-dataset.png)

docs/how_to/save_detections.md

@@ -19,7 +19,6 @@ 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
@@ -34,7 +33,6 @@ model. You can learn more on this topic in our
     ```
 
 === "Ultralytics"
-
     ```python
     import supervision as sv
     from ultralytics import YOLO
@@ -49,7 +47,6 @@ model. You can learn more on this topic in our
     ```
 
 === "Transformers"
-
     ```python
     import torch
     import supervision as sv
@@ -83,7 +80,6 @@ and then pass the
 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
@@ -100,7 +96,6 @@ object resulting from the inference to it. Its fields are parsed and saved on di
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="7 12" }
     import supervision as sv
     from ultralytics import YOLO
@@ -117,7 +112,6 @@ object resulting from the inference to it. Its fields are parsed and saved on di
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="9 23" }
     import torch
     import supervision as sv
@@ -144,11 +138,11 @@ object resulting from the inference to it. Its fields are parsed and saved on di
             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        |
+| 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
 
@@ -160,7 +154,6 @@ also allows you to add custom information to each row, which can be passed via t
 frame index from which the detections originate.
 
 === "Inference"
-
     ```{ .py hl_lines="8 12" }
     import supervision as sv
     from inference import get_model
@@ -177,7 +170,6 @@ frame index from which the detections originate.
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="8 12" }
     import supervision as sv
     from ultralytics import YOLO
@@ -194,7 +186,6 @@ frame index from which the detections originate.
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="10 23" }
     import torch
     import supervision as sv
@@ -221,11 +212,11 @@ frame index from which the detections originate.
             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           |
+| 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
 
@@ -236,7 +227,6 @@ 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
@@ -253,7 +243,6 @@ with
     ```
 
 === "Ultralytics"
-
     ```{ .py hl_lines="7" }
     import supervision as sv
     from ultralytics import YOLO
@@ -270,7 +259,6 @@ with
     ```
 
 === "Transformers"
-
     ```{ .py hl_lines="9" }
     import torch
     import supervision as sv

docs/how_to/track_objects.md

@@ -32,7 +32,7 @@ download_assets(VideoAssets.PEOPLE_WALKING)
 First, you'll need to obtain predictions from your object detection or segmentation
 model. In this tutorial, we are using the YOLOv8 model as an example. However,
 Supervision is versatile and compatible with various models. Check this
-[link](latest/how_to/detect_and_annotate/#load-predictions-into-supervision)
+[link](/latest/how_to/detect_and_annotate/#load-predictions-into-supervision)
 for guidance on how to plug in other models.
 
 We will define a `callback` function, which will process each frame of the video
@@ -41,7 +41,6 @@ This `callback` function will be essential in the subsequent steps of the tutori
 it will be modified to include tracking, labeling, and trace annotations.
 
 === "Ultralytics"
-
     ```{ .py }
     import numpy as np
     import supervision as sv
@@ -63,7 +62,6 @@ it will be modified to include tracking, labeling, and trace annotations.
     ```
 
 === "Inference"
-
     ```{ .py }
     import numpy as np
     import supervision as sv
@@ -97,7 +95,6 @@ functionality, each detected object is assigned a unique tracker ID,
 enabling the continuous following of the object's motion path across different frames.
 
 === "Ultralytics"
-
     ```{ .py hl_lines="6 12" }
     import numpy as np
     import supervision as sv
@@ -121,7 +118,6 @@ enabling the continuous following of the object's motion path across different f
     ```
 
 === "Inference"
-
     ```{ .py hl_lines="6 12" }
     import numpy as np
     import supervision as sv
@@ -148,12 +144,11 @@ enabling the continuous following of the object's motion path across different f
 
 Annotating the video with tracking IDs helps in distinguishing and following each object
 distinctly. With the
-[`sv.LabelAnnotator`](/latest/annotators.md/#supervision.annotators.core.LabelAnnotator)
+[`sv.LabelAnnotator`](/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator)
 in Supervision, we can overlay the tracker IDs and class labels on the detected objects,
 offering a clear visual representation of each object's class and unique identifier.
 
 === "Ultralytics"
-
     ```{ .py hl_lines="8 15-19 23-24" }
     import numpy as np
     import supervision as sv
@@ -188,7 +183,6 @@ offering a clear visual representation of each object's class and unique identif
     ```
 
 === "Inference"
-
     ```{ .py hl_lines="8 15-19 23-24" }
     import numpy as np
     import supervision as sv
@@ -230,12 +224,11 @@ offering a clear visual representation of each object's class and unique identif
 
 Adding traces to the video involves overlaying the historical paths of the detected
 objects. This feature, powered by the
-[`sv.TraceAnnotator`](/latest/annotators/#supervision.annotators.core.TraceAnnotator),
+[`sv.TraceAnnotator`](/latest/detection/annotators/#supervision.annotators.core.TraceAnnotator),
 allows for visualizing the trajectories of objects, helping in understanding the
 movement patterns and interactions between objects in the video.
 
 === "Ultralytics"
-
     ```{ .py hl_lines="9 26-27" }
     import numpy as np
     import supervision as sv
@@ -273,7 +266,6 @@ movement patterns and interactions between objects in the video.
     ```
 
 === "Inference"
-
     ```{ .py hl_lines="9 26-27" }
     import numpy as np
     import supervision as sv

docs/index.md

@@ -34,25 +34,18 @@ You can install `supervision` in a
 [**Python>=3.8**](https://www.python.org/) environment.
 
 !!! example "pip install (recommended)"
-
-    === "headless"
-        The headless installation of `supervision` is designed for environments where graphical user interfaces (GUI) are not needed, making it more lightweight and suitable for server-side applications.
+    === "pip"
+        [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
+        [![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)
 
         ```bash
         pip install supervision
         ```
 
-    === "desktop"
-        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]"
-        ```
-
 !!! 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
@@ -60,7 +53,6 @@ You can install `supervision` in a
         ```
 
     === "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
@@ -68,9 +60,7 @@ You can install `supervision` in a
         ```
 
 !!! example "git clone (for development)"
-
     === "virtualenv"
-
         ```bash
         # clone repository and navigate to root directory
         git clone https://github.com/roboflow/supervision.git
@@ -81,15 +71,11 @@ You can install `supervision` in a
         source venv/bin/activate
         pip install --upgrade pip
 
-        # headless install
+        # installation
         pip install -e "."
-
-        # desktop install
-        pip install -e ".[desktop]"
         ```
 
     === "poetry"
-
         ```bash
         # clone repository and navigate to root directory
         git clone https://github.com/roboflow/supervision.git
@@ -99,18 +85,15 @@ You can install `supervision` in a
         poetry env use python3.10
         poetry shell
 
-        # headless install
+        # installation
         poetry install
-
-        # desktop install
-        poetry install --extras "desktop"
         ```
 
 ## 🚀 Quickstart
 
 <div class="grid cards" markdown>
 
--   __Detect and Annotate__
+- **Detect and Annotate**
 
     ---
 
@@ -118,7 +101,7 @@ You can install `supervision` in a
 
     [:octicons-arrow-right-24: Tutorial](how_to/detect_and_annotate.md)
 
--   __Track Objects__
+- **Track Objects**
 
     ---
 
@@ -126,7 +109,7 @@ You can install `supervision` in a
 
     [:octicons-arrow-right-24: Tutorial](how_to/track_objects.md)
 
--   __Detect Small Objects__
+- **Detect Small Objects**
 
     ---
 
@@ -134,25 +117,26 @@ You can install `supervision` in a
 
     [:octicons-arrow-right-24: Tutorial](how_to/detect_small_objects.md)
 
--   > __Count Objects Crossing Line__
+- **Count Objects Crossing Line**
 
     ---
 
     Explore methods to accurately count and analyze objects crossing a predefined line
 
--   > __Filter Objects in Zone__
+    [:octicons-arrow-right-24: Notebook](https://supervision.roboflow.com/latest/notebooks/count-objects-crossing-the-line/)
+
+- > **Filter Objects in Zone**
 
     ---
 
     Master the techniques to selectively filter and focus on objects within a specific zone
 
--   **Cheatsheet**
+- **Cheatsheet**
 
-    ***
+    ---
 
     Access a quick reference guide to the most common `supervision` functions
 
     [:octicons-arrow-right-24: Cheatsheet](https://roboflow.github.io/cheatsheet-supervision/)
 
-
 </div>

docs/javascripts/cookbooks-card.js

@@ -28,16 +28,15 @@ document.addEventListener("DOMContentLoaded", function () {
     }, {});
 
 
-  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');
+    async function renderCard(element, elementIndex) {
+        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 `
+        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}"
@@ -45,18 +44,18 @@ document.addEventListener("DOMContentLoaded", function () {
                 ${label.trim()}
             </span>
         `;
-    }).join(' ') : '';
+        }).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();
-    }));
+        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 `
+        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}"
@@ -75,10 +74,10 @@ document.addEventListener("DOMContentLoaded", function () {
                 </a>
             </div>
         `;
-    }).join('');
+        }).join('');
 
-    let authorNamesHTML = authorDataArray.map(
-        authorData => `
+        let authorNamesHTML = authorDataArray.map(
+            authorData => `
             <span
                 class="author-name"
                 data-login="${authorData.login}-${elementIndex}"
@@ -88,54 +87,52 @@ document.addEventListener("DOMContentLoaded", function () {
                 ${authorData.login}
             </a>
         </span>`
-    ).join(',&nbsp;');
+        ).join(',&nbsp;');
 
-    let authorsHTML = `
+        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">
+        element.innerText = `
+            <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;">
-              <img src="/assets/supervision-lenny.png" aria-label="stars" width="20" height="20" role="img" />
-              &nbsp;
-              <span style="margin-left: 4px">${version}</span>
+                <span style="font-weight: 700; font-size: 1rem; color: ${theme.linkColor};">
+                ${name}
+                </span>
             </div>
-            <div style="display: flex; align-items: center; flex-wrap: wrap">
-              ${labelHTML}
+            ${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>
         </div>
-      </a>
-        `
+        `;
 
-    let sanitizedHTML = DOMPurify.sanitize(element.innerText);
-    element.innerHTML = sanitizedHTML;
+        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');
+        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');
+            });
         });
-
-        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/core.md

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

docs/metrics/f1_score.md

@@ -0,0 +1,18 @@
+---
+comments: true
+status: new
+---
+
+# F1 Score
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.f1_score.F1Score">F1Score</a></h2>
+</div>
+
+:::supervision.metrics.f1_score.F1Score
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.f1_score.F1ScoreResult">F1ScoreResult</a></h2>
+</div>
+
+:::supervision.metrics.f1_score.F1ScoreResult

docs/metrics/mean_average_precision.md

@@ -0,0 +1,18 @@
+---
+comments: true
+status: new
+---
+
+# Mean Average Precision
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.mean_average_precision.MeanAveragePrecision">MeanAveragePrecision</a></h2>
+</div>
+
+:::supervision.metrics.mean_average_precision.MeanAveragePrecision
+
+<div class="md-typeset">
+    <h2><a href="#supervision.metrics.mean_average_precision.MeanAveragePrecisionResult">MeanAveragePrecisionResult</a></h2>
+</div>
+
+:::supervision.metrics.mean_average_precision.MeanAveragePrecisionResult

docs/notebooks/annotate-video-with-detections.ipynb

@@ -287,10 +287,10 @@
             ],
             "source": [
                 "# Create a bounding box annotator object.\n",
-                "bounding_box = sv.BoundingBoxAnnotator()\n",
+                "box_annotator = sv.BoxAnnotator()\n",
                 "\n",
                 "# Annotate our frame with detections.\n",
-                "annotated_frame = bounding_box.annotate(scene=frame.copy(), detections=detections)\n",
+                "annotated_frame = box_annotator.annotate(scene=frame.copy(), detections=detections)\n",
                 "\n",
                 "# Display the frame.\n",
                 "sv.plot_image(annotated_frame)"
@@ -302,7 +302,7 @@
                 "id": "o8SsyCid6YV3"
             },
             "source": [
-                "Notice that we create a `box_annoator` variable by initalizing a [BoundingBoxAnnotator](https://supervision.roboflow.com/latest/annotators/#boundingboxannotator). We can change the color and thickness, but for simplicity we keep the defaults. There are a ton of easy to use [annotators](https://supervision.roboflow.com/latest/annotators/) available in the Supervision package other than a bounding box that are fun to play with."
+                "Notice that we create a `box_annotator` variable by initalizing a [BoxAnnotator](https://supervision.roboflow.com/latest/detection/annotators/#boxannotator). We can change the color and thickness, but for simplicity we keep the defaults. There are a ton of easy to use [annotators](https://supervision.roboflow.com/latest/detection/annotators/) available in the Supervision package other than a bounding box that are fun to play with."
             ]
         },
         {
@@ -342,7 +342,7 @@
                 "        detections = sv.Detections.from_inference(result)\n",
                 "\n",
                 "        # Apply bounding box to detections on a copy of the frame.\n",
-                "        annotated_frame = bounding_box.annotate(\n",
+                "        annotated_frame = box_annotator.annotate(\n",
                 "            scene=frame.copy(),\n",
                 "            detections=detections\n",
                 "        )\n",
@@ -368,7 +368,7 @@
                 "<br>\n",
                 "\n",
                 "\n",
-                "In the code above we've created a`video_info` variable to pass information about the video to our `VideoSink`. The `VideoSink` is a cool little context manager that allows us to `write_frames()` to a video ouput file. We're also optionally using `tqdm` to display a progress bar with a % complete. We only scratched the surface of all of the customizable Annotators and additional features that Supervision and Inference have to offer. Stay tuned for more cookbooks on how to take advantge of them in your computer vision applications. Happy building! \ud83d\ude80"
+                "In the code above we've created a`video_info` variable to pass information about the video to our `VideoSink`. The `VideoSink` is a cool little context manager that allows us to `write_frames()` to a video output file. We're also optionally using `tqdm` to display a progress bar with a % complete. We only scratched the surface of all of the customizable Annotators and additional features that Supervision and Inference have to offer. Stay tuned for more cookbooks on how to take advantage of them in your computer vision applications. Happy building! \ud83d\ude80"
             ]
         }
     ],

docs/notebooks/occupancy_analytics.ipynb

@@ -951,7 +951,7 @@
             },
             "source": [
                 "#### Import your data\n",
-                "To load your data back in, upload the saved file to the Colab enviorment and run the code cell."
+                "To load your data back in, upload the saved file to the Colab environment and run the code cell."
             ]
         },
         {

docs/notebooks/serialise-detections-to-csv.ipynb

@@ -10,7 +10,7 @@
                 "\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/detections-to-jsonsink.ipynb)\n",
+                "[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow/supervision/blob/develop/docs/notebooks/serialise-detections-to-csv.ipynb)\n",
                 "\n",
                 "This cookbook introduce [sv.CSVSink](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink) tool designed to write captured object detection data to file from video streams/file"
             ]

docs/notebooks/serialise-detections-to-json.ipynb

@@ -10,7 +10,7 @@
                 "\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/detections-to-jsonsink.ipynb)\n",
+                "[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow/supervision/blob/develop/docs/notebooks/serialise-detections-to-json.ipynb)\n",
                 "\n",
                 "This cookbook introduce [sv.JSONSink](https://supervision.roboflow.com/develop/detection/tools/save_detections/#supervision.detection.tools.json_sink.JSONSink) tool designed to write captured object detection data to file from video streams/file"
             ]

docs/stylesheets/cookbooks-card.css

@@ -19,6 +19,16 @@
     }
 }
 
+.custom-grid a {
+    color: inherit;
+    text-decoration: none;
+    display: block;
+}
+
+.custom-grid a:hover {
+    color: inherit; /* Ensure color does not change on hover */
+}
+
 .repo-card {
     background: radial-gradient(at right top, #A351FB25, #A5F9EA25);
     border-radius: 0.5rem;

docs/theme/cookbooks.html

@@ -11,17 +11,49 @@
       <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>
-      <p class="card repo-card" data-url="/develop/notebooks/serialise-detections-to-csv" data-name="Serialise Detections to a CSV File"  data-labels="DETECTIONS,CSV SINK,INFERENCE" data-version="v0.21.0" data-author="onuralpszr"></p>
-      <p class="card repo-card" data-url="/develop/notebooks/serialise-detections-to-json" data-name="Serialise Detections to a JSON File"  data-labels="DETECTIONS,JSON SINK,INFERENCE" data-version="v0.21.0" data-author="onuralpszr"></p>
-
+      <a href="/develop/notebooks/quickstart"> <p class="card repo-card" data-name="Supervision Quickstart" data-labels="ANNOTATOR,DETECTION,SAM"
+          data-version="v0.18.0" data-author="SkalskiP,onuralpszr"></p>
+      </a>
+      <a href="/develop/notebooks/count-objects-crossing-the-line">
+        <p class="card repo-card" data-name="Count Objects Crossing the Line"
+          data-labels="ANNOTATORS,LINE ZONE,TRACKING" data-version="v0.18.0" data-author="SkalskiP"></p>
+      </a>
+      <a href="/develop/notebooks/zero-shot-object-detection-with-yolo-world">
+        <p class="card repo-card" data-name="Zero-Shot Object Detection with YOLO-World"
+          data-labels="ANNOTATORS,DETECTION,INFERENCE" data-version="v0.19.0" data-author="SkalskiP"></p>
+      </a>
+      <a href="/develop/notebooks/download-supervision-assets">
+        <p class="card repo-card" data-name="Downloading Supervision Assets" data-labels="ASSETS" data-version="v0.18.0"
+          data-author="nickherrig"></p>
+      </a>
+      <a href="/develop/notebooks/annotate-video-with-detections">
+        <p class="card repo-card" data-name="Annotate Video with Detections" data-labels="INFERENCE,YOLOV8"
+          data-version="v0.18.0" data-author="nickherrig"></p>
+      </a>
+      <a href="/develop/notebooks/object-tracking">
+        <p class="card repo-card" data-name="Object Tracking" data-labels="TRACKING, ANNOTATOR" data-version="v0.18.0"
+          data-author="nickherrig"></p>
+      </a>
+      <a href="/develop/notebooks/occupancy_analytics">
+        <p class="card repo-card" data-name="Analyzing Zone Occupancy" data-labels="ANNOTATOR,DETECTION,ZONES"
+          data-version="v0.19.0" data-author="stellasphere"></p>
+      </a>
+      <a href="/develop/notebooks/evaluating-alignment-of-text-to-image-diffusion-models">
+        <p class="card repo-card" data-name="Evaluating Alignment of Text-to-image Diffusion Models"
+          data-labels="ANNOTATORS,YOLO WORLD" data-version="v0.19.0rc5" data-author="iamhatesz"></p>
+      </a>
+      <a href="/develop/notebooks/serialise-detections-to-csv">
+        <p class="card repo-card" data-name="Serialise Detections to a CSV File"
+          data-labels="DETECTIONS,CSV SINK,INFERENCE" data-version="v0.21.0" data-author="onuralpszr"></p>
+      </a>
+      <a href="/develop/notebooks/serialise-detections-to-json">
+        <p class="card repo-card" data-name="Serialise Detections to a JSON File"
+          data-labels="DETECTIONS,JSON SINK,INFERENCE" data-version="v0.21.0" data-author="onuralpszr"></p>
+      </a>
+      <a href="/develop/notebooks/small-object-detection-with-sahi">
+        <p class="card repo-card" data-name="Small Object Detection with SAHI"
+          data-labels="DETECTIONS,SAHI,SMALL,OBJECT,INFERENCE" data-version="v0.23.0" data-author="ediardo"></p>
+      </a>
     </div>
   </div>
 </section>

docs/utils/draw.md

@@ -28,6 +28,12 @@ comments: true
 
 :::supervision.draw.utils.draw_polygon
 
+<div class="md-typeset">
+    <h2><a href="#supervision.draw.utils.draw_filled_polygon">draw_filled_polygon</a></h2>
+</div>
+
+:::supervision.draw.utils.draw_filled_polygon
+
 <div class="md-typeset">
     <h2><a href="#supervision.draw.utils.draw_text">draw_text</a></h2>
 </div>

docs/utils/file.md

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

examples/count_people_in_zone/README.md

@@ -16,67 +16,76 @@ https://github.com/roboflow/supervision/assets/26109316/f84db7b5-79e2-4142-a1da-
 
 - clone repository and navigate to example directory
 
-  ```bash
-  git clone https://github.com/roboflow/supervision.git
-  cd supervision/examples/count_people_in_zone
-  ```
+    ```bash
+    git clone https://github.com/roboflow/supervision.git
+    cd supervision/examples/count_people_in_zone
+    ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
+    ```bash
+    python3 -m venv venv
+    source venv/bin/activate
+    ```
 
 - install required dependencies
 
-  ```bash
-  pip install -r requirements.txt
-  ```
+    ```bash
+    pip install -r requirements.txt
+    ```
 
 - download `traffic_analysis.pt` and `traffic_analysis.mov` files
 
-  ```bash
-  ./setup.sh
-  ```
+    ```bash
+    ./setup.sh
+    ```
 
 ## 🛠️ script arguments
 
 - ultralytics
 
-  - `--source_weights_path` (optional): The path to the YOLO model's weights file.
-    Defaults to `"yolov8x.pt"` if not specified.
+    - `--source_weights_path` (optional): The path to the YOLO model's weights file.
+        Defaults to `"yolov8x.pt"` if not specified.
 
-  - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
-    configurations. This file defines the polygonal areas in the video where objects will
-    be counted.
-  - `--source_video_path`: The path to the source video file that will be analyzed.
-  - `--target_video_path` (optional): The path to save the output video with annotations.
-    If not provided, the processed video will be displayed in real-time.
-  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
-    to filter detections. Default is `0.3`.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model. Default is `0.7`.
+    - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
+        configurations. This file defines the polygonal areas in the video where objects will
+        be counted.
+
+    - `--source_video_path`: The path to the source video file that will be analyzed.
+
+    - `--target_video_path` (optional): The path to save the output video with annotations.
+        If not provided, the processed video will be displayed in real-time.
+
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
+        to filter detections. Default is `0.3`.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model. Default is `0.7`.
 
 - inference
 
-  - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
-    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-    to acquire your `API KEY`.
-  - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
-    value is `"yolov8x-1280"`.
+    - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+        directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+        variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+        to acquire your `API KEY`.
 
-  - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
-    configurations. This file defines the polygonal areas in the video where objects will
-    be counted.
-  - `--source_video_path`: The path to the source video file that will be analyzed.
-  - `--target_video_path` (optional): The path to save the output video with annotations.
-    If not provided, the processed video will be displayed in real-time.
-  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
-    to filter detections. Default is `0.3`.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model. Default is `0.7`.
+    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+        value is `"yolov8x-1280"`.
+
+    - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
+        configurations. This file defines the polygonal areas in the video where objects will
+        be counted.
+
+    - `--source_video_path`: The path to the source video file that will be analyzed.
+
+    - `--target_video_path` (optional): The path to save the output video with annotations.
+        If not provided, the processed video will be displayed in real-time.
+
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
+        to filter detections. Default is `0.3`.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model. Default is `0.7`.
 
 ## 📌 zone configuration
 
@@ -89,35 +98,35 @@ https://github.com/roboflow/supervision/assets/26109316/f84db7b5-79e2-4142-a1da-
 
 - ultralytics
 
-  ```bash
-  python ultralytics_example.py \
-  --zone_configuration_path data/multi-zone-config.json \
-  --source_video_path data/market-square.mp4 \
-  --confidence_threshold 0.3 \
-  --iou_threshold 0.5
-  ```
+    ```bash
+    python ultralytics_example.py \
+        --zone_configuration_path data/multi-zone-config.json \
+        --source_video_path data/market-square.mp4 \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5
+    ```
 
 - inference
 
-  ```bash
-  python inference_example.py \
-  --roboflow_api_key <ROBOFLOW API KEY> \
-  --zone_configuration_path data/multi-zone-config.json \
-  --source_video_path data/market-square.mp4 \
-  --confidence_threshold 0.3 \
-  --iou_threshold 0.5
-  ```
+    ```bash
+    python inference_example.py \
+        --roboflow_api_key <ROBOFLOW API KEY> \
+        --zone_configuration_path data/multi-zone-config.json \
+        --source_video_path data/market-square.mp4 \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5
+    ```
 
 ## © 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.
+    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.
+    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/count_people_in_zone/inference_example.py

@@ -75,7 +75,7 @@ def detect(
         frame (np.ndarray): The frame to process, expected to be a NumPy array.
         model (RoboflowInferenceModel): The Inference model used for processing the
             frame.
-        confidence_threshold (float, optional): The confidence threshold for filtering
+        confidence_threshold (float): The confidence threshold for filtering
             detections. Default is 0.5.
 
     Returns:

examples/count_people_in_zone/ultralytics_example.py

@@ -72,7 +72,7 @@ def detect(
     Args:
         frame (np.ndarray): The frame to process, expected to be a NumPy array.
         model (YOLO): The YOLO model used for processing the frame.
-        confidence_threshold (float, optional): The confidence threshold for filtering
+        confidence_threshold (float): The confidence threshold for filtering
             detections. Default is 0.5.
 
     Returns:

examples/heatmap_and_track/README.md

@@ -6,7 +6,6 @@ This script performs heatmap and tracking analysis using YOLOv8, an object-detec
 ByteTrack, a simple yet effective online multi-object tracking method. It uses the
 supervision package for multiple tasks such as drawing heatmap annotations, tracking objects, etc.
 
-
 ## 💻 install
 
 - clone repository and navigate to example directory
@@ -16,7 +15,7 @@ supervision package for multiple tasks such as drawing heatmap annotations, trac
     cd supervision/examples/heatmap_and_track
     ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
     ```bash
     python3 -m venv venv
@@ -32,17 +31,17 @@ supervision package for multiple tasks such as drawing heatmap annotations, trac
 ## 🛠️ script arguments
 
 - `--source_weights_path`: Required. Specifies the path to the weights file for the
-YOLO model. This file contains the trained model data necessary for object detection.
+    YOLO model. This file contains the trained model data necessary for object detection.
 - `--source_video_path` (optional): The path to the source video file that will be
-analyzed. This is the input video on which crowd analysis will be performed.
-If not specified default is `people-walking.mp4` from supervision assets
+    analyzed. This is the input video on which crowd analysis will be performed.
+    If not specified default is `people-walking.mp4` from supervision assets
 - `--target_video_path` (optional): The path to save the output.mp4 video with annotations.
 - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
-to filter detections. Default is `0.3`. This determines how confident the model should
-be to recognize an object in the video.
+    to filter detections. Default is `0.3`. This determines how confident the model should
+    be to recognize an object in the video.
 - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-for the model. Default is 0.7. This value is used to manage object detection accuracy,
-particularly in distinguishing between different objects.
+    for the model. Default is 0.7. This value is used to manage object detection accuracy,
+    particularly in distinguishing between different objects.
 - `--heatmap_alpha` (optional): Opacity of the overlay mask, between 0 and 1.
 - `--radius` (optional): Radius of the heat circle.
 - `--track_threshold` (optional): Detection confidence threshold for track activation.
@@ -53,11 +52,11 @@ particularly in distinguishing between different objects.
 
 ```bash
 python script.py \
---source_weights_path weight.pt \
---source_video_path  input_video.mp4 \
---confidence_threshold 0.3 \
---iou_threshold 0.5 \
---target_video_path  output_video.mp4
+    --source_weights_path weight.pt \
+    --source_video_path  input_video.mp4 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.5 \
+    --target_video_path  output_video.mp4
 ```
 
 ## © license
@@ -65,11 +64,11 @@ python script.py \
 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.
+    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.
+    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/heatmap_and_track/script.py

@@ -20,9 +20,9 @@ def heatmap_and_track(
     iou_threshold: float = 0.5,
     heatmap_alpha: float = 0.5,
     radius: int = 25,
-    track_threshold: float = 0.35,
+    track_activation_threshold: float = 0.35,
     track_seconds: int = 5,
-    match_threshold: float = 0.99,
+    minimum_matching_threshold: float = 0.99,
 ) -> None:
     ### instantiate model
     model = YOLO(source_weights_path)
@@ -47,9 +47,9 @@ def heatmap_and_track(
 
     ### tracker config
     byte_tracker = sv.ByteTrack(
-        track_thresh=track_threshold,
-        track_buffer=track_seconds * fps,
-        match_thresh=match_threshold,
+        track_activation_threshold=track_activation_threshold,
+        lost_track_buffer=track_seconds * fps,
+        minimum_matching_threshold=minimum_matching_threshold,
         frame_rate=fps,
     )
 
@@ -175,7 +175,7 @@ if __name__ == "__main__":
         iou_threshold=args.iou_threshold,
         heatmap_alpha=args.heatmap_alpha,
         radius=args.radius,
-        track_threshold=args.track_threshold,
+        track_activation_threshold=args.track_threshold,
         track_seconds=args.track_seconds,
-        match_threshold=args.match_threshold,
+        minimum_matching_threshold=args.match_threshold,
     )

examples/speed_estimation/README.md

@@ -11,7 +11,7 @@ supervision package for multiple tasks such as tracking, annotations, etc.
 
 https://github.com/roboflow/supervision/assets/26109316/d50118c1-2ae4-458d-915a-5d860fd36f71
 
-> [!IMPORTANT]
+> \[!IMPORTANT\]
 > Adjust the [`SOURCE`](https://github.com/roboflow/supervision/blob/e32b05a636dab2ea1f39299e529c4b22b8baa8da/examples/speed_estimation/ultralytics_example.py#L10)
 > and [`TARGET`](https://github.com/roboflow/supervision/blob/e32b05a636dab2ea1f39299e529c4b22b8baa8da/examples/speed_estimation/ultralytics_example.py#L15)
 > configuration if you plan to run a speed estimation script on your video file. Those must be adjusted separately for each camera view. You can learn more
@@ -21,97 +21,102 @@ https://github.com/roboflow/supervision/assets/26109316/d50118c1-2ae4-458d-915a-
 
 - clone repository and navigate to example directory
 
-  ```bash
-  git clone https://github.com/roboflow/supervision.git
-  cd supervision/examples/speed_estimation
-  ```
+    ```bash
+    git clone https://github.com/roboflow/supervision.git
+    cd supervision/examples/speed_estimation
+    ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
-  ```bash
-  python3.10 -m venv venv
-  source venv/bin/activate
-  ```
+    ```bash
+    python3.10 -m venv venv
+    source venv/bin/activate
+    ```
 
 - install required dependencies
 
-  ```bash
-  pip install -r requirements.txt
-  ```
+    ```bash
+    pip install -r requirements.txt
+    ```
 
 - download `vehicles.mp4` file
 
-  ```bash
-  python3.10 video_downloader.py
-  ```
+    ```bash
+    python3.10 video_downloader.py
+    ```
 
 ## 🛠️ script arguments
 
 - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
-  directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-  variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-  to acquire your `API KEY`.
+    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+    to acquire your `API KEY`.
+
 - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
-  value is `"yolov8x-1280"`.
+    value is `"yolov8x-1280"`.
 
 - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
-  file, which is essential for the object detection process. This file contains the
-  data that the model uses to identify objects in the video.
+    file, which is essential for the object detection process. This file contains the
+    data that the model uses to identify objects in the video.
+
 - `--source_video_path`: Required. The path to the source video file that will be
-  analyzed. This is the input video on which traffic flow analysis will be performed.
+    analyzed. This is the input video on which traffic flow analysis will be performed.
+
 - `--target_video_path`: The path to save the output video with
-  annotations. If not specified, the processed video will be displayed in real-time
-  without being saved.
+    annotations. If not specified, the processed video will be displayed in real-time
+    without being saved.
+
 - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
-  model to filter detections. Default is `0.3`. This determines how confident the
-  model should be to recognize an object in the video.
+    model to filter detections. Default is `0.3`. This determines how confident the
+    model should be to recognize an object in the video.
+
 - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-  for the model. Default is 0.7. This value is used to manage object detection
-  accuracy, particularly in distinguishing between different objects.
+    for the model. Default is 0.7. This value is used to manage object detection
+    accuracy, particularly in distinguishing between different objects.
 
 ## ⚙️ run
 
 - yolo-nas
 
-  ```bash
+    ```bash
     python yolo_nas_example.py \
-    --source_video_path data/vehicles.mp4 \
-    --target_video_path data/vehicles-result.mp4 \
-    --confidence_threshold 0.3 \
-    --iou_threshold 0.5
-  ```
+        --source_video_path data/vehicles.mp4 \
+        --target_video_path data/vehicles-result.mp4 \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5
+    ```
 
 - inference
 
-  ```bash
+    ```bash
     python inference_example.py \
-    --roboflow_api_key <ROBOFLOW API KEY> \
-    --source_video_path data/vehicles.mp4 \
-    --target_video_path data/vehicles-result.mp4 \
-    --confidence_threshold 0.3 \
-    --iou_threshold 0.5
-  ```
+        --roboflow_api_key <ROBOFLOW API KEY> \
+        --source_video_path data/vehicles.mp4 \
+        --target_video_path data/vehicles-result.mp4 \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5
+    ```
 
 - ultralytics
 
-  ```bash
+    ```bash
     python ultralytics_example.py \
-    --source_video_path data/vehicles.mp4 \
-    --target_video_path data/vehicles-result.mp4 \
-    --confidence_threshold 0.3 \
-    --iou_threshold 0.5
-  ```
+        --source_video_path data/vehicles.mp4 \
+        --target_video_path data/vehicles-result.mp4 \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5
+    ```
 
 ## © 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.
+    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.
+    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/speed_estimation/inference_example.py

@@ -95,7 +95,7 @@ if __name__ == "__main__":
     model = get_roboflow_model(model_id=args.model_id, api_key=args.roboflow_api_key)
 
     byte_track = sv.ByteTrack(
-        frame_rate=video_info.fps, track_thresh=args.confidence_threshold
+        frame_rate=video_info.fps, track_activation_threshold=args.confidence_threshold
     )
 
     thickness = sv.calculate_optimal_line_thickness(

examples/speed_estimation/ultralytics_example.py

@@ -73,7 +73,7 @@ if __name__ == "__main__":
     model = YOLO("yolov8x.pt")
 
     byte_track = sv.ByteTrack(
-        frame_rate=video_info.fps, track_thresh=args.confidence_threshold
+        frame_rate=video_info.fps, track_activation_threshold=args.confidence_threshold
     )
 
     thickness = sv.calculate_optimal_line_thickness(

examples/speed_estimation/yolo_nas_example.py

@@ -74,7 +74,7 @@ if __name__ == "__main__":
     model = models.get(Models.YOLO_NAS_L, pretrained_weights="coco")
 
     byte_track = sv.ByteTrack(
-        frame_rate=video_info.fps, track_thresh=args.confidence_threshold
+        frame_rate=video_info.fps, track_activation_threshold=args.confidence_threshold
     )
 
     thickness = sv.calculate_optimal_line_thickness(

examples/time_in_zone/README.md

@@ -15,23 +15,23 @@ https://github.com/roboflow/supervision/assets/26109316/d051cc8a-dd15-41d4-aa36-
 
 - clone repository and navigate to example directory
 
-  ```bash
-  git clone https://github.com/roboflow/supervision.git
-  cd supervision/examples/time_in_zone
-  ```
+    ```bash
+    git clone https://github.com/roboflow/supervision.git
+    cd supervision/examples/time_in_zone
+    ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
+    ```bash
+    python3 -m venv venv
+    source venv/bin/activate
+    ```
 
 - install required dependencies
 
-  ```bash
-  pip install -r requirements.txt
-  ```
+    ```bash
+    pip install -r requirements.txt
+    ```
 
 ## 🛠 scripts
 
@@ -45,16 +45,16 @@ This script allows you to download a video from YouTube.
 
 ```bash
 python scripts/download_from_youtube.py \
---url "https://www.youtube.com/watch?v=-8zyEwAa50Q" \
---output_path "data/checkout" \
---file_name "video.mp4"
+    --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"
+    --url "https://www.youtube.com/watch?v=MNn9qKG2UFI" \
+    --output_path "data/traffic" \
+    --file_name "video.mp4"
 ```
 
 ### `stream_from_file`
@@ -68,14 +68,14 @@ mock a live video stream for local testing. Video will be streamed in a loop und
 
 ```bash
 python scripts/stream_from_file.py \
---video_directory "data/checkout" \
---number_of_streams 1
+    --video_directory "data/checkout" \
+    --number_of_streams 1
 ```
 
 ```bash
 python scripts/stream_from_file.py \
---video_directory "data/traffic" \
---number_of_streams 1
+    --video_directory "data/traffic" \
+    --number_of_streams 1
 ```
 
 ### `draw_zones`
@@ -86,24 +86,27 @@ window where you can draw polygons on the source image or video file. The polygo
 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"
+    --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"
+    --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
@@ -114,33 +117,33 @@ https://github.com/roboflow/supervision/assets/26109316/9d514c9e-2a61-418b-ae49-
 
 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`.
+- `--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
+    --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
+    --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
@@ -149,31 +152,31 @@ https://github.com/roboflow/supervision/assets/26109316/5ec896d7-4b39-4426-8979-
 
 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`.
+- `--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
+    --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
+    --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>
@@ -183,68 +186,68 @@ python inference_stream_example.py \
 
 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`.
+- `--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
+    --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
+    --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`.
+- `--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
+    --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
+    --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>
@@ -254,11 +257,11 @@ python ultralytics_stream_example.py \
 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.
+    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.
+    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/utils/timers.py

@@ -22,7 +22,7 @@ class FPSBasedTimer:
         """Initializes the FPSBasedTimer with the specified frames per second rate.
 
         Args:
-            fps (int, optional): The frame rate of the video stream. Defaults to 30.
+            fps (int): The frame rate of the video stream. Defaults to 30.
         """
         self.fps = fps
         self.frame_id = 0

examples/tracking/README.md

@@ -9,93 +9,100 @@ detection and Supervision for tracking and annotation.
 
 - clone repository and navigate to example directory
 
-  ```bash
-  git clone https://github.com/roboflow/supervision.git
-  cd supervision/examples/tracking
-  ```
+    ```bash
+    git clone https://github.com/roboflow/supervision.git
+    cd supervision/examples/tracking
+    ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
+    ```bash
+    python3 -m venv venv
+    source venv/bin/activate
+    ```
 
 - install required dependencies
 
-  ```bash
-  pip install -r requirements.txt
-  ```
+    ```bash
+    pip install -r requirements.txt
+    ```
 
 ## 🛠️ script arguments
 
 - ultralytics
 
-  - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
-    file, which is essential for the object detection process. This file contains the data
-    that the model uses to identify objects in the video.
+    - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
+        file, which is essential for the object detection process. This file contains the data
+        that the model uses to identify objects in the video.
 
-  - `--source_video_path`: Required. The path to the source video file to be processed.
-    This is the video on which object detection and annotation will be performed.
-  - `--target_video_path`: Required. The path where the processed video, with annotations
-    added, will be saved. This is your output video file.
-  - `--confidence_threshold` (optional): Sets the confidence level at which the model
-    identifies objects in the video. Default is `0.3`. A higher threshold makes the model
-    more selective, while a lower threshold makes it more inclusive in identifying objects.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model, defaulting to `0.7`. This parameter helps in differentiating between
-    distinct objects, especially in crowded scenes.
+    - `--source_video_path`: Required. The path to the source video file to be processed.
+        This is the video on which object detection and annotation will be performed.
+
+    - `--target_video_path`: Required. The path where the processed video, with annotations
+        added, will be saved. This is your output video file.
+
+    - `--confidence_threshold` (optional): Sets the confidence level at which the model
+        identifies objects in the video. Default is `0.3`. A higher threshold makes the model
+        more selective, while a lower threshold makes it more inclusive in identifying objects.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model, defaulting to `0.7`. This parameter helps in differentiating between
+        distinct objects, especially in crowded scenes.
 
 - inference
 
-  - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
-    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-    to acquire your `API KEY`.
-  - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
-    value is `"yolov8x-1280"`.
+    - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+        directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+        variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+        to acquire your `API KEY`.
 
-  - `--source_video_path`: Required. The path to the source video file to be processed.
-    This is the video on which object detection and annotation will be performed.
-  - `--target_video_path`: Required. The path where the processed video, with annotations
-    added, will be saved. This is your output video file.
-  - `--confidence_threshold` (optional): Sets the confidence level at which the model
-    identifies objects in the video. Default is `0.3`. A higher threshold makes the model
-    more selective, while a lower threshold makes it more inclusive in identifying objects.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model, defaulting to `0.7`. This parameter helps in differentiating between
-    distinct objects, especially in crowded scenes.
+    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+        value is `"yolov8x-1280"`.
+
+    - `--source_video_path`: Required. The path to the source video file to be processed.
+        This is the video on which object detection and annotation will be performed.
+
+    - `--target_video_path`: Required. The path where the processed video, with annotations
+        added, will be saved. This is your output video file.
+
+    - `--confidence_threshold` (optional): Sets the confidence level at which the model
+        identifies objects in the video. Default is `0.3`. A higher threshold makes the model
+        more selective, while a lower threshold makes it more inclusive in identifying objects.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model, defaulting to `0.7`. This parameter helps in differentiating between
+        distinct objects, especially in crowded scenes.
 
 ## ⚙️ run
 
 - inference
 
-  ```bash
-  python inference_example.py \
-  --roboflow_api_key <ROBOFLOW API KEY> \
-  --source_video_path input.mp4 \
-  --target_video_path tracking_result.mp4
-  ```
+    ```bash
+    python inference_example.py \
+        --roboflow_api_key <ROBOFLOW API KEY> \
+        --source_video_path input.mp4 \
+        --target_video_path tracking_result.mp4
+    ```
 
 - ultralytics
 
-  ```bash
-  python ultralytics_example.py \
-  --source_weights_path yolov8s.pt \
-  --source_video_path input.mp4 \
-  --target_video_path tracking_result.mp4
-  ```
+    ```bash
+    python ultralytics_example.py \
+        --source_weights_path yolov8s.pt \
+        --source_video_path input.mp4 \
+        --target_video_path tracking_result.mp4
+    ```
 
 ## © 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.
+    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.
+    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/traffic_analysis/README.md

@@ -12,105 +12,112 @@ https://github.com/roboflow/supervision/assets/26109316/c9436828-9fbf-4c25-ae8c-
 
 - clone repository and navigate to example directory
 
-  ```bash
-  git clone https://github.com/roboflow/supervision.git
-  cd supervision/examples/traffic_analysis
-  ```
+    ```bash
+    git clone https://github.com/roboflow/supervision.git
+    cd supervision/examples/traffic_analysis
+    ```
 
-- setup python environment and activate it [optional]
+- setup python environment and activate it \[optional\]
 
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
+    ```bash
+    python3 -m venv venv
+    source venv/bin/activate
+    ```
 
 - install required dependencies
 
-  ```bash
-  pip install -r requirements.txt
-  ```
+    ```bash
+    pip install -r requirements.txt
+    ```
 
 - download `traffic_analysis.pt` and `traffic_analysis.mov` files
 
-  ```bash
-  ./setup.sh
-  ```
+    ```bash
+    ./setup.sh
+    ```
 
 ## 🛠️ script arguments
 
 - ultralytics
 
-  - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
-    file, which is essential for the object detection process. This file contains the
-    data that the model uses to identify objects in the video.
+    - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
+        file, which is essential for the object detection process. This file contains the
+        data that the model uses to identify objects in the video.
 
-  - `--source_video_path`: Required. The path to the source video file that will be
-    analyzed. This is the input video on which traffic flow analysis will be performed.
-  - `--target_video_path` (optional): The path to save the output video with
-    annotations. If not specified, the processed video will be displayed in real-time
-    without being saved.
-  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
-    model to filter detections. Default is `0.3`. This determines how confident the
-    model should be to recognize an object in the video.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model. Default is 0.7. This value is used to manage object detection
-    accuracy, particularly in distinguishing between different objects.
+    - `--source_video_path`: Required. The path to the source video file that will be
+        analyzed. This is the input video on which traffic flow analysis will be performed.
+
+    - `--target_video_path` (optional): The path to save the output video with
+        annotations. If not specified, the processed video will be displayed in real-time
+        without being saved.
+
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
+        model to filter detections. Default is `0.3`. This determines how confident the
+        model should be to recognize an object in the video.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model. Default is 0.7. This value is used to manage object detection
+        accuracy, particularly in distinguishing between different objects.
 
 - inference
 
-  - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
-    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-    to acquire your `API KEY`.
-  - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
-    value is `"vehicle-count-in-drone-video/6"`.
+    - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+        directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+        variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+        to acquire your `API KEY`.
 
-  - `--source_video_path`: Required. The path to the source video file that will be
-    analyzed. This is the input video on which traffic flow analysis will be performed.
-  - `--target_video_path` (optional): The path to save the output video with
-    annotations. If not specified, the processed video will be displayed in real-time
-    without being saved.
-  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
-    model to filter detections. Default is `0.3`. This determines how confident the
-    model should be to recognize an object in the video.
-  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
-    for the model. Default is 0.7. This value is used to manage object detection
-    accuracy, particularly in distinguishing between different objects.
+    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+        value is `"vehicle-count-in-drone-video/6"`.
+
+    - `--source_video_path`: Required. The path to the source video file that will be
+        analyzed. This is the input video on which traffic flow analysis will be performed.
+
+    - `--target_video_path` (optional): The path to save the output video with
+        annotations. If not specified, the processed video will be displayed in real-time
+        without being saved.
+
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
+        model to filter detections. Default is `0.3`. This determines how confident the
+        model should be to recognize an object in the video.
+
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+        for the model. Default is 0.7. This value is used to manage object detection
+        accuracy, particularly in distinguishing between different objects.
 
 ## ⚙️ run
 
 - ultralytics
 
-  ```bash
-  python ultralytics_example.py \
-  --source_weights_path data/traffic_analysis.pt \
-  --source_video_path data/traffic_analysis.mov \
-  --confidence_threshold 0.3 \
-  --iou_threshold 0.5 \
-  --target_video_path data/traffic_analysis_result.mov
-  ```
+    ```bash
+    python ultralytics_example.py \
+        --source_weights_path data/traffic_analysis.pt \
+        --source_video_path data/traffic_analysis.mov \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5 \
+        --target_video_path data/traffic_analysis_result.mov
+    ```
 
 - inference
 
-  ```bash
-  python inference_example.py \
-  --roboflow_api_key <ROBOFLOW API KEY> \
-  --source_video_path data/traffic_analysis.mov \
-  --confidence_threshold 0.3 \
-  --iou_threshold 0.5 \
-  --target_video_path data/traffic_analysis_result.mov
-  ```
+    ```bash
+    python inference_example.py \
+        --roboflow_api_key <ROBOFLOW API KEY> \
+        --source_video_path data/traffic_analysis.mov \
+        --confidence_threshold 0.3 \
+        --iou_threshold 0.5 \
+        --target_video_path data/traffic_analysis_result.mov
+    ```
 
 ## © 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.
+    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.
+    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/traffic_analysis/inference_example.py

@@ -1,6 +1,6 @@
 import argparse
 import os
-from typing import Dict, Iterable, List, Set
+from typing import Dict, Iterable, List, Optional, Set
 
 import cv2
 import numpy as np
@@ -77,7 +77,7 @@ class VideoProcessor:
         roboflow_api_key: str,
         model_id: str,
         source_video_path: str,
-        target_video_path: str = None,
+        target_video_path: Optional[str] = None,
         confidence_threshold: float = 0.3,
         iou_threshold: float = 0.7,
     ) -> None:

examples/traffic_analysis/ultralytics_example.py

@@ -1,5 +1,5 @@
 import argparse
-from typing import Dict, Iterable, List, Set
+from typing import Dict, Iterable, List, Optional, Set
 
 import cv2
 import numpy as np
@@ -74,7 +74,7 @@ class VideoProcessor:
         self,
         source_weights_path: str,
         source_video_path: str,
-        target_video_path: str = None,
+        target_video_path: Optional[str] = None,
         confidence_threshold: float = 0.3,
         iou_threshold: float = 0.7,
     ) -> None:

mkdocs.yml

@@ -33,7 +33,6 @@ extra_css:
   - stylesheets/extra.css
   - stylesheets/cookbooks-card.css
 
-
 nav:
   - Supervision: index.md
   - Learn:
@@ -42,52 +41,54 @@ nav:
       - Filter Detections: how_to/filter_detections.md
       - Detect Small Objects: how_to/detect_small_objects.md
       - Track Objects on Video: how_to/track_objects.md
+      - Process Datasets: how_to/process_datasets.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
-    - Trackers: trackers.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
-        - Draw: utils/draw.md
-        - Geometry: utils/geometry.md
-    - Assets: assets.md
+      - Detection and Segmentation:
+          - Core: detection/core.md
+          - Annotators: detection/annotators.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
+      - Trackers: trackers.md
+      - Datasets:
+          - Core: datasets/core.md
+          - Utils: datasets/utils.md
+      - Metrics:
+          - mAP: metrics/mean_average_precision.md
+          - F1 Score: metrics/f1_score.md
+          - Legacy Metrics: detection/metrics.md
+      - Utils:
+          - Video: utils/video.md
+          - Image: utils/image.md
+          - Iterables: utils/iterables.md
+          - Notebook: utils/notebook.md
+          - File: utils/file.md
+          - Draw: utils/draw.md
+          - Geometry: utils/geometry.md
+      - Assets: assets.md
   - Cookbooks: cookbooks.md
   - Cheatsheet: https://roboflow.github.io/cheatsheet-supervision/
   - Contribute:
-    - Contributing: contributing.md
-    - Code of Conduct: code_of_conduct.md
-    - License: license.md
+      - Contributing: contributing.md
+      - Code of Conduct: code_of_conduct.md
+      - License: license.md
   - Release Notes:
-        - Changelog: changelog.md
-        - Deprecated: deprecated.md
-
-
+      - Changelog: changelog.md
+      - Deprecated: deprecated.md
 
 theme:
-  name: 'material'
+  name: "material"
   icon:
     edit: material/pencil
   logo: assets/supervision-lenny.png
@@ -104,19 +105,18 @@ theme:
   palette:
     # Palette for light mode
     - scheme: default
-      primary: 'custom'
+      primary: "custom"
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
 
     # Palette toggle for dark mode
     - scheme: slate
-      primary: 'custom'
+      primary: "custom"
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
 
-
   font:
     text: Roboto
     code: Roboto Mono
@@ -127,10 +127,10 @@ theme:
 plugins:
   - search
   - mkdocs-jupyter:
-        kernel_name: python3
-        execute: false
-        include_source: True
-        include_requirejs: true
+      kernel_name: python3
+      execute: false
+      include_source: True
+      include_requirejs: true
   - mkdocstrings:
       default_handler: python
       handlers:
@@ -154,8 +154,6 @@ plugins:
   - git-revision-date-localized:
       enable_creation_date: true
 
-
-
 markdown_extensions:
   - admonition
   - pymdownx.details

pyproject.toml

@@ -1,15 +1,18 @@
 [tool.poetry]
 name = "supervision"
-version = "0.22.0"
+version = "0.24.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>"]
+maintainers = [
+    "Piotr Skalski <piotr.skalski92@gmail.com>",
+    "Linas Kondrackis <linas@roboflow.com>",
+]
 readme = "README.md"
 license = "MIT"
 packages = [{ include = "supervision" }]
 homepage = "https://github.com/roboflow/supervision"
 repository = "https://github.com/roboflow/supervision"
-documentation = "https://github.com/roboflow/supervision/blob/main/README.md"
+documentation = "https://supervision.roboflow.com/latest/"
 keywords = [
     "machine-learning",
     "deep-learning",
@@ -40,7 +43,10 @@ classifiers = [
 
 [tool.poetry.dependencies]
 python = "^3.8"
-numpy = ">=1.21.2"
+numpy = [
+    { version = ">=1.21.2,<1.23.3", python = "<=3.10" },
+    { version = ">=1.23.3", python = ">3.10" },
+]
 scipy = [
     { version = "1.10.0", python = "<3.9" },
     { version = "^1.10.0", python = ">=3.9" },
@@ -48,20 +54,22 @@ 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.32.3", optional = true }
-tqdm = { version = ">=4.62.3,<=4.66.4", optional = true }
 pillow = ">=9.4"
+requests = { version = ">=2.26.0,<=2.32.3", optional = true }
+tqdm = { version = ">=4.62.3,<=4.66.5", optional = true }
+# pandas: picked lowest major version that supports Python 3.8
+pandas = { version = ">=2.0.0", optional = true }
+pandas-stubs = { version = ">=2.0.0.230412", optional = true }
+opencv-python = ">=4.5.5.64"
 
 [tool.poetry.extras]
-desktop = ["opencv-python"]
 assets = ["requests", "tqdm"]
+metrics = ["pandas", "pandas-stubs"]
 
 [tool.poetry.group.dev.dependencies]
 twine = "^5.1.1"
 pytest = ">=7.2.2,<9.0.0"
-wheel = ">=0.40,<0.44"
+wheel = ">=0.40,<0.45"
 build = ">=0.10,<1.3"
 ruff = ">=0.1.0"
 mypy = "^1.4.1"
@@ -76,20 +84,26 @@ docutils = [
     { version = "^0.21.1", python = ">=3.9" },
 ]
 
-
 [tool.poetry.group.docs.dependencies]
 mkdocs-material = { extras = ["imaging"], version = "^9.5.5" }
-mkdocstrings = { extras = ["python"], version = ">=0.20,<0.26" }
+mkdocstrings = ">=0.25.2,<0.27.0"
+mkdocstrings-python = "^1.10.9"
 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-committers-plugin-2 = "^2.4.1"
 mkdocs-git-revision-date-localized-plugin = "^1.2.4"
 
-[tool.isort]
-line_length = 88
-profile = "black"
+[tool.poetry.group.typecheck]
+optional = true
+
+[tool.poetry.group.typecheck.dependencies]
+types-pyyaml = "^6.0.12.20240808"
+types-cffi = "^1.16.0.20240331"
+types-requests = "^2.32.0.20240712"
+types-tqdm = "^4.66.0.20240417"
+
 
 [tool.bandit]
 target = ["test", "supervision"]
@@ -99,24 +113,6 @@ tests = ["B201", "B301", "B318", "B314", "B303", "B413", "B412", "B410"]
 check = true
 imports = ["cv2", "supervision"]
 
-[tool.black]
-target-version = ["py38"]
-line-length = 88
-include = '\.pyi?$'
-exclude = '''
-/(
-    \.git
-  | \.hg
-  | \.mypy_cache
-  | \.tox
-  | \.venv
-  | _build
-  | buck-out
-  | build
-  | dist
-  | docs
-)/
-'''
 
 [tool.ruff]
 target-version = "py38"
@@ -154,7 +150,7 @@ indent-width = 4
 
 [tool.ruff.lint]
 # Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default.
-select = ["E", "F"]
+select = ["E", "F", "I", "A", "Q", "W", "RUF"]
 ignore = []
 # Allow autofix for all enabled rules (when `--fix`) is provided.
 fixable = [
@@ -223,6 +219,10 @@ convention = "google"
 # Flag errors (`C901`) whenever the complexity level exceeds 5.
 max-complexity = 20
 
+[tool.ruff.lint.isort]
+order-by-type = true
+no-sections = false
+
 [tool.ruff.format]
 # Like Black, use double quotes for strings.
 quote-style = "double"
@@ -236,6 +236,12 @@ skip-magic-trailing-comma = false
 # Like Black, automatically detect the appropriate line ending.
 line-ending = "auto"
 
+[tool.codespell]
+skip = "*.ipynb,poetry.lock"
+count = true
+quiet-level = 3
+ignore-words-list = "STrack,sTrack,strack"
+
 [tool.setuptools]
 include-package-data = false
 

release_process.md

@@ -6,14 +6,19 @@ It assumes you already have the code changes, as well as a draft of the release
 
 1. Make sure you have all required changes were merged into `develop`.
 2. Create and merge a PR, merging `develop` into `main`, containing:
-   - A commit that updates the project version in `pyproject.toml`.
-   - All changes made during the release.
+    - A commit that updates the project version in `pyproject.toml`.
+    - All changes made during the release.
 3. Tag the commit with the new supervision version.
-   - Upon pushing the tag, the [PyPi](https://pypi.org/project/supervision/) should update to the new version. Check this!
+    - make sure to pull from `main` !
+    - Verify that the latest merge commits exists. `git log`.
+    - Run `git tag x.y.z`, with your version
+    - Check with `git log`.
+    - Run `git push origin --tags`
+    - Upon pushing the tag, the [PyPi](https://pypi.org/project/supervision/) should update to the new version. Check this!
 4. Open and merge a PR, merging `main` into `develop`.
 5. Update the docs by running the [Supervision Release Documentation Workflow 📚](https://github.com/roboflow/supervision/actions/workflows/publish-release-docs.yml) workflow from GitHub.
     - Select the `main` branch from the dropdown.
 6. Create a release on GitHub.
-   - Go to releases
-   - Assign the release notes to the tag created in step 3.
-   - Publish the release.
+    - Go to releases
+    - Assign the release notes to the tag created in step 3.
+    - Publish the release.

supervision/__init__.py

@@ -7,6 +7,7 @@ except importlib_metadata.PackageNotFoundError:
     __version__ = "development"
 
 from supervision.annotators.core import (
+    BackgroundOverlayAnnotator,
     BlurAnnotator,
     BoundingBoxAnnotator,
     BoxAnnotator,
@@ -18,6 +19,7 @@ from supervision.annotators.core import (
     EllipseAnnotator,
     HaloAnnotator,
     HeatMapAnnotator,
+    IconAnnotator,
     LabelAnnotator,
     MaskAnnotator,
     OrientedBoxAnnotator,
@@ -38,7 +40,11 @@ from supervision.dataset.core import (
 )
 from supervision.dataset.utils import mask_to_rle, rle_to_mask
 from supervision.detection.core import Detections
-from supervision.detection.line_zone import LineZone, LineZoneAnnotator
+from supervision.detection.line_zone import (
+    LineZone,
+    LineZoneAnnotator,
+    LineZoneAnnotatorMulticlass,
+)
 from supervision.detection.lmm import LMM
 from supervision.detection.overlap_filter import (
     OverlapFilter,
@@ -63,6 +69,7 @@ from supervision.detection.utils import (
     mask_to_xyxy,
     move_boxes,
     move_masks,
+    oriented_box_iou_batch,
     pad_boxes,
     polygon_to_mask,
     polygon_to_xyxy,
@@ -74,6 +81,7 @@ from supervision.draw.color import Color, ColorPalette
 from supervision.draw.utils import (
     calculate_optimal_line_thickness,
     calculate_optimal_text_scale,
+    draw_filled_polygon,
     draw_filled_rectangle,
     draw_image,
     draw_line,

supervision/annotators/core.py

@@ -1,9 +1,11 @@
+from functools import lru_cache
 from math import sqrt
 from typing import List, Optional, Tuple, Union
 
 import cv2
 import numpy as np
-from PIL import ImageDraw, ImageFont
+import numpy.typing as npt
+from PIL import Image, ImageDraw, ImageFont
 
 from supervision.annotators.base import BaseAnnotator, ImageType
 from supervision.annotators.utils import (
@@ -22,7 +24,12 @@ from supervision.utils.conversion import (
     ensure_cv2_image_for_annotation,
     ensure_pil_image_for_annotation,
 )
-from supervision.utils.image import crop_image, overlay_image, scale_image
+from supervision.utils.image import (
+    crop_image,
+    letterbox_image,
+    overlay_image,
+    scale_image,
+)
 from supervision.utils.internal import deprecated
 
 
@@ -42,7 +49,7 @@ class BoxAnnotator(BaseAnnotator):
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating detections.
             thickness (int): Thickness of the bounding box lines.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.color: Union[Color, ColorPalette] = color
@@ -61,7 +68,8 @@ class BoxAnnotator(BaseAnnotator):
 
         Args:
             scene (ImageType): The image where bounding boxes will be drawn. `ImageType`
-            is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`.
+                is a flexible type, accepting either `numpy.ndarray` or
+                `PIL.Image.Image`.
             detections (Detections): Object detections to annotate.
             custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
                 Allows to override the default color mapping strategy.
@@ -87,6 +95,7 @@ class BoxAnnotator(BaseAnnotator):
         ![bounding-box-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/bounding-box-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
             color = resolve_color(
@@ -127,7 +136,7 @@ class BoundingBoxAnnotator(BaseAnnotator):
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating detections.
             thickness (int): Thickness of the bounding box lines.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.color: Union[Color, ColorPalette] = color
@@ -172,6 +181,7 @@ class BoundingBoxAnnotator(BaseAnnotator):
         ![bounding-box-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/bounding-box-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
             color = resolve_color(
@@ -208,7 +218,7 @@ class OrientedBoxAnnotator(BaseAnnotator):
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating detections.
             thickness (int): Thickness of the bounding box lines.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.color: Union[Color, ColorPalette] = color
@@ -256,12 +266,13 @@ class OrientedBoxAnnotator(BaseAnnotator):
             )
             ```
         """  # noqa E501 // docs
-
+        assert isinstance(scene, np.ndarray)
         if detections.data is None or ORIENTED_BOX_COORDINATES not in detections.data:
             return scene
+        obb_boxes = np.array(detections.data[ORIENTED_BOX_COORDINATES]).astype(int)
 
         for detection_idx in range(len(detections)):
-            bbox = np.intp(detections.data.get(ORIENTED_BOX_COORDINATES)[detection_idx])
+            obb = obb_boxes[detection_idx]
             color = resolve_color(
                 color=self.color,
                 detections=detections,
@@ -271,7 +282,7 @@ class OrientedBoxAnnotator(BaseAnnotator):
                 else custom_color_lookup,
             )
 
-            cv2.drawContours(scene, [bbox], 0, color.as_bgr(), self.thickness)
+            cv2.drawContours(scene, [obb], 0, color.as_bgr(), self.thickness)
 
         return scene
 
@@ -296,7 +307,7 @@ class MaskAnnotator(BaseAnnotator):
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating detections.
             opacity (float): Opacity of the overlay mask. Must be between `0` and `1`.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.color: Union[Color, ColorPalette] = color
@@ -342,6 +353,7 @@ class MaskAnnotator(BaseAnnotator):
         ![mask-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/mask-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         if detections.mask is None:
             return scene
 
@@ -385,7 +397,7 @@ class PolygonAnnotator(BaseAnnotator):
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating detections.
             thickness (int): Thickness of the polygon lines.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.color: Union[Color, ColorPalette] = color
@@ -431,6 +443,7 @@ class PolygonAnnotator(BaseAnnotator):
         ![polygon-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/polygon-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         if detections.mask is None:
             return scene
 
@@ -471,7 +484,7 @@ class ColorAnnotator(BaseAnnotator):
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating detections.
             opacity (float): Opacity of the overlay mask. Must be between `0` and `1`.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.color: Union[Color, ColorPalette] = color
@@ -517,6 +530,7 @@ class ColorAnnotator(BaseAnnotator):
         ![box-mask-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/box-mask-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         scene_with_boxes = scene.copy()
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
@@ -565,7 +579,7 @@ class HaloAnnotator(BaseAnnotator):
             opacity (float): Opacity of the overlay mask. Must be between `0` and `1`.
             kernel_size (int): The size of the average pooling kernel used for creating
                 the halo.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.color: Union[Color, ColorPalette] = color
@@ -612,6 +626,7 @@ class HaloAnnotator(BaseAnnotator):
         ![halo-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/halo-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         if detections.mask is None:
             return scene
         colored_mask = np.zeros_like(scene, dtype=np.uint8)
@@ -663,7 +678,7 @@ class EllipseAnnotator(BaseAnnotator):
             thickness (int): Thickness of the ellipse lines.
             start_angle (int): Starting angle of the ellipse.
             end_angle (int): Ending angle of the ellipse.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.color: Union[Color, ColorPalette] = color
@@ -711,6 +726,7 @@ class EllipseAnnotator(BaseAnnotator):
         ![ellipse-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/ellipse-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
             color = resolve_color(
@@ -755,7 +771,7 @@ class BoxCornerAnnotator(BaseAnnotator):
                 annotating detections.
             thickness (int): Thickness of the corner lines.
             corner_length (int): Length of each corner line.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.color: Union[Color, ColorPalette] = color
@@ -802,6 +818,7 @@ class BoxCornerAnnotator(BaseAnnotator):
         ![box-corner-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/box-corner-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
             color = resolve_color(
@@ -843,7 +860,7 @@ class CircleAnnotator(BaseAnnotator):
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating detections.
             thickness (int): Thickness of the circle line.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
 
@@ -891,6 +908,7 @@ class CircleAnnotator(BaseAnnotator):
         ![circle-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/circle-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
             center = ((x1 + x2) // 2, (y1 + y2) // 2)
@@ -927,6 +945,7 @@ class DotAnnotator(BaseAnnotator):
         position: Position = Position.CENTER,
         color_lookup: ColorLookup = ColorLookup.CLASS,
         outline_thickness: int = 0,
+        outline_color: Union[Color, ColorPalette] = Color.BLACK,
     ):
         """
         Args:
@@ -937,12 +956,16 @@ class DotAnnotator(BaseAnnotator):
             color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
             outline_thickness (int): Thickness of the outline of the dot.
+            outline_color (Union[Color, ColorPalette]): The color or color palette to
+                use for outline. It is activated by setting outline_thickness to a value
+                greater than 0.
         """
         self.color: Union[Color, ColorPalette] = color
         self.radius: int = radius
         self.position: Position = position
         self.color_lookup: ColorLookup = color_lookup
         self.outline_thickness = outline_thickness
+        self.outline_color: Union[Color, ColorPalette] = outline_color
 
     @ensure_cv2_image_for_annotation
     def annotate(
@@ -983,6 +1006,7 @@ class DotAnnotator(BaseAnnotator):
         ![dot-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/dot-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         xy = detections.get_anchors_coordinates(anchor=self.position)
         for detection_idx in range(len(detections)):
             color = resolve_color(
@@ -997,8 +1021,20 @@ class DotAnnotator(BaseAnnotator):
 
             cv2.circle(scene, center, self.radius, color.as_bgr(), -1)
             if self.outline_thickness:
+                outline_color = resolve_color(
+                    color=self.outline_color,
+                    detections=detections,
+                    detection_idx=detection_idx,
+                    color_lookup=self.color_lookup
+                    if custom_color_lookup is None
+                    else custom_color_lookup,
+                )
                 cv2.circle(
-                    scene, center, self.radius, (0, 0, 0), self.outline_thickness
+                    scene,
+                    center,
+                    self.radius,
+                    outline_color.as_bgr(),
+                    self.outline_thickness,
                 )
         return scene
 
@@ -1011,7 +1047,7 @@ class LabelAnnotator(BaseAnnotator):
     def __init__(
         self,
         color: Union[Color, ColorPalette] = ColorPalette.DEFAULT,
-        text_color: Color = Color.WHITE,
+        text_color: Union[Color, ColorPalette] = Color.WHITE,
         text_scale: float = 0.5,
         text_thickness: int = 1,
         text_padding: int = 10,
@@ -1023,20 +1059,21 @@ class LabelAnnotator(BaseAnnotator):
         Args:
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating the text background.
-            text_color (Color): The color to use for the text.
+            text_color (Union[Color, ColorPalette]): The color or color palette to use
+                for the text.
             text_scale (float): Font scale for the text.
             text_thickness (int): Thickness of the text characters.
             text_padding (int): Padding around the text within its background box.
             text_position (Position): Position of the text relative to the detection.
                 Possible values are defined in the `Position` enum.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
             border_radius (int): The radius to apply round edges. If the selected
                 value is higher than the lower dimension, width or height, is clipped.
         """
         self.border_radius: int = border_radius
         self.color: Union[Color, ColorPalette] = color
-        self.text_color: Color = text_color
+        self.text_color: Union[Color, ColorPalette] = text_color
         self.text_scale: float = text_scale
         self.text_thickness: int = text_thickness
         self.text_padding: int = text_padding
@@ -1091,6 +1128,7 @@ class LabelAnnotator(BaseAnnotator):
         ![label-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/label-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         font = cv2.FONT_HERSHEY_SIMPLEX
         anchors_coordinates = detections.get_anchors_coordinates(
             anchor=self.text_anchor
@@ -1114,10 +1152,21 @@ class LabelAnnotator(BaseAnnotator):
                 ),
             )
 
+            text_color = resolve_color(
+                color=self.text_color,
+                detections=detections,
+                detection_idx=detection_idx,
+                color_lookup=(
+                    self.color_lookup
+                    if custom_color_lookup is None
+                    else custom_color_lookup
+                ),
+            )
+
             if labels is not None:
                 text = labels[detection_idx]
-            elif detections[CLASS_NAME_DATA_FIELD] is not None:
-                text = detections[CLASS_NAME_DATA_FIELD][detection_idx]
+            elif CLASS_NAME_DATA_FIELD in detections.data:
+                text = detections.data[CLASS_NAME_DATA_FIELD][detection_idx]
             elif detections.class_id is not None:
                 text = str(detections.class_id[detection_idx])
             else:
@@ -1152,7 +1201,7 @@ class LabelAnnotator(BaseAnnotator):
                 org=(text_x, text_y),
                 fontFace=font,
                 fontScale=self.text_scale,
-                color=self.text_color.as_rgb(),
+                color=text_color.as_bgr(),
                 thickness=self.text_thickness,
                 lineType=cv2.LINE_AA,
             )
@@ -1210,7 +1259,7 @@ class RichLabelAnnotator(BaseAnnotator):
     def __init__(
         self,
         color: Union[Color, ColorPalette] = ColorPalette.DEFAULT,
-        text_color: Color = Color.WHITE,
+        text_color: Union[Color, ColorPalette] = Color.WHITE,
         font_path: Optional[str] = None,
         font_size: int = 10,
         text_padding: int = 10,
@@ -1222,7 +1271,7 @@ class RichLabelAnnotator(BaseAnnotator):
         Args:
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating the text background.
-            text_color (Color): The color to use for the text.
+            text_color (Union[Color, ColorPalette]): The color to use for the text.
             font_path (Optional[str]): Path to the font file (e.g., ".ttf" or ".otf")
                 to use for rendering text. If `None`, the default PIL font will be used.
             font_size (int): Font size for the text.
@@ -1296,6 +1345,7 @@ class RichLabelAnnotator(BaseAnnotator):
             ```
 
         """
+        assert isinstance(scene, Image.Image)
         draw = ImageDraw.Draw(scene)
         anchors_coordinates = detections.get_anchors_coordinates(
             anchor=self.text_anchor
@@ -1317,10 +1367,22 @@ class RichLabelAnnotator(BaseAnnotator):
                     else custom_color_lookup
                 ),
             )
+
+            text_color = resolve_color(
+                color=self.text_color,
+                detections=detections,
+                detection_idx=detection_idx,
+                color_lookup=(
+                    self.color_lookup
+                    if custom_color_lookup is None
+                    else custom_color_lookup
+                ),
+            )
+
             if labels is not None:
                 text = labels[detection_idx]
-            elif detections[CLASS_NAME_DATA_FIELD] is not None:
-                text = detections[CLASS_NAME_DATA_FIELD][detection_idx]
+            elif CLASS_NAME_DATA_FIELD in detections.data:
+                text = detections.data[CLASS_NAME_DATA_FIELD][detection_idx]
             elif detections.class_id is not None:
                 text = str(detections.class_id[detection_idx])
             else:
@@ -1350,7 +1412,7 @@ class RichLabelAnnotator(BaseAnnotator):
                 xy=(text_x, text_y),
                 text=text,
                 font=self.font,
-                fill=self.text_color.as_rgb(),
+                fill=text_color.as_rgb(),
             )
         return scene
 
@@ -1368,6 +1430,106 @@ class RichLabelAnnotator(BaseAnnotator):
         return font
 
 
+class IconAnnotator(BaseAnnotator):
+    """
+    A class for drawing an icon on an image, using provided detections.
+    """
+
+    def __init__(
+        self,
+        icon_resolution_wh: Tuple[int, int] = (64, 64),
+        icon_position: Position = Position.TOP_CENTER,
+        offset_xy: Tuple[int, int] = (0, 0),
+    ):
+        """
+        Args:
+            icon_resolution_wh (Tuple[int, int]): The size of drawn icons.
+                All icons will be resized to this resolution, keeping the aspect ratio.
+            icon_position (Position): The position of the icon.
+            offset_xy (Tuple[int, int]): The offset to apply to the icon position,
+                in pixels. Can be both positive and negative.
+        """
+        self.icon_resolution_wh = icon_resolution_wh
+        self.position = icon_position
+        self.offset_xy = offset_xy
+
+    @ensure_cv2_image_for_annotation
+    def annotate(
+        self, scene: ImageType, detections: Detections, icon_path: Union[str, List[str]]
+    ) -> ImageType:
+        """
+        Annotates the given scene with given icons.
+
+        Args:
+            scene (ImageType): The image where labels will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
+            detections (Detections): Object detections to annotate.
+            icon_path (Union[str, List[str]]): The path to the PNG image to use as an
+                icon. Must be a single path or a list of paths, one for each detection.
+                Pass an empty string `""` to draw nothing.
+
+        Returns:
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
+
+        Example:
+            ```python
+            import supervision as sv
+
+            image = ...
+            detections = sv.Detections(...)
+
+            available_icons = ["roboflow.png", "lenny.png"]
+            icon_paths = [np.random.choice(available_icons) for _ in detections]
+
+            icon_annotator = sv.IconAnnotator()
+            annotated_frame = icon_annotator.annotate(
+                scene=image.copy(),
+                detections=detections,
+                icon_path=icon_paths
+            )
+            ```
+
+        ![icon-annotator-example](https://media.roboflow.com/
+        supervision-annotator-examples/icon-annotator-example.png)
+        """
+        assert isinstance(scene, np.ndarray)
+        if isinstance(icon_path, list) and len(icon_path) != len(detections):
+            raise ValueError(
+                f"The number of icon paths provided ({len(icon_path)}) does not match "
+                f"the number of detections ({len(detections)}). Either provide a single"
+                f" icon path or one for each detection."
+            )
+
+        xy = detections.get_anchors_coordinates(anchor=self.position).astype(int)
+
+        for detection_idx in range(len(detections)):
+            current_path = (
+                icon_path if isinstance(icon_path, str) else icon_path[detection_idx]
+            )
+            if current_path == "":
+                continue
+            icon = self._load_icon(current_path)
+            icon_h, icon_w = icon.shape[:2]
+
+            x = int(xy[detection_idx, 0] - icon_w / 2 + self.offset_xy[0])
+            y = int(xy[detection_idx, 1] - icon_h / 2 + self.offset_xy[1])
+
+            scene[:] = overlay_image(scene, icon, (x, y))
+        return scene
+
+    @lru_cache
+    def _load_icon(self, icon_path: str) -> np.ndarray:
+        icon = cv2.imread(icon_path, cv2.IMREAD_UNCHANGED)
+        if icon is None:
+            raise FileNotFoundError(
+                f"Error: Couldn't load the icon image from {icon_path}"
+            )
+        icon = letterbox_image(image=icon, resolution_wh=self.icon_resolution_wh)
+        return icon
+
+
 class BlurAnnotator(BaseAnnotator):
     """
     A class for blurring regions in an image using provided detections.
@@ -1416,6 +1578,7 @@ class BlurAnnotator(BaseAnnotator):
         ![blur-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/blur-annotator-example-purple.png)
         """
+        assert isinstance(scene, np.ndarray)
         image_height, image_width = scene.shape[:2]
         clipped_xyxy = clip_boxes(
             xyxy=detections.xyxy, resolution_wh=(image_width, image_height)
@@ -1457,7 +1620,7 @@ class TraceAnnotator(BaseAnnotator):
             trace_length (int): The maximum length of the trace in terms of historical
                 points. Defaults to `30`.
             thickness (int): The thickness of the trace lines. Defaults to `2`.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.color: Union[Color, ColorPalette] = color
@@ -1514,8 +1677,14 @@ class TraceAnnotator(BaseAnnotator):
         ![trace-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/trace-annotator-example-purple.png)
         """
-        self.trace.put(detections)
+        assert isinstance(scene, np.ndarray)
+        if detections.tracker_id is None:
+            raise ValueError(
+                "The `tracker_id` field is missing in the provided detections."
+                " See more: https://supervision.roboflow.com/latest/how_to/track_objects"
+            )
 
+        self.trace.put(detections)
         for detection_idx in range(len(detections)):
             tracker_id = int(detections.tracker_id[detection_idx])
             color = resolve_color(
@@ -1568,9 +1737,9 @@ class HeatMapAnnotator(BaseAnnotator):
         self.opacity = opacity
         self.radius = radius
         self.kernel_size = kernel_size
-        self.heat_mask = None
         self.top_hue = top_hue
         self.low_hue = low_hue
+        self.heat_mask: Optional[npt.NDArray[np.float32]] = None
 
     @ensure_cv2_image_for_annotation
     def annotate(self, scene: ImageType, detections: Detections) -> ImageType:
@@ -1597,7 +1766,7 @@ class HeatMapAnnotator(BaseAnnotator):
             heat_map_annotator = sv.HeatMapAnnotator()
 
             video_info = sv.VideoInfo.from_video_path(video_path='...')
-            frames_generator = get_video_frames_generator(source_path='...')
+            frames_generator = sv.get_video_frames_generator(source_path='...')
 
             with sv.VideoSink(target_path='...', video_info=video_info) as sink:
                for frame in frames_generator:
@@ -1612,12 +1781,20 @@ class HeatMapAnnotator(BaseAnnotator):
         ![heatmap-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/heat-map-annotator-example-purple.png)
         """
-
+        assert isinstance(scene, np.ndarray)
         if self.heat_mask is None:
-            self.heat_mask = np.zeros(scene.shape[:2])
+            self.heat_mask = np.zeros(scene.shape[:2], dtype=np.float32)
+
         mask = np.zeros(scene.shape[:2])
         for xy in detections.get_anchors_coordinates(self.position):
-            cv2.circle(mask, (int(xy[0]), int(xy[1])), self.radius, 1, -1)
+            x, y = int(xy[0]), int(xy[1])
+            cv2.circle(
+                img=mask,
+                center=(x, y),
+                radius=self.radius,
+                color=(1,),
+                thickness=-1,  # fill
+            )
         self.heat_mask = mask + self.heat_mask
         temp = self.heat_mask.copy()
         temp = self.low_hue - temp / temp.max() * (self.low_hue - self.top_hue)
@@ -1685,6 +1862,7 @@ class PixelateAnnotator(BaseAnnotator):
         ![pixelate-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/pixelate-annotator-example-10.png)
         """
+        assert isinstance(scene, np.ndarray)
         image_height, image_width = scene.shape[:2]
         clipped_xyxy = clip_boxes(
             xyxy=detections.xyxy, resolution_wh=(image_width, image_height)
@@ -1720,6 +1898,7 @@ class TriangleAnnotator(BaseAnnotator):
         position: Position = Position.TOP_CENTER,
         color_lookup: ColorLookup = ColorLookup.CLASS,
         outline_thickness: int = 0,
+        outline_color: Union[Color, ColorPalette] = Color.BLACK,
     ):
         """
         Args:
@@ -1731,6 +1910,9 @@ class TriangleAnnotator(BaseAnnotator):
             color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
             outline_thickness (int): Thickness of the outline of the triangle.
+            outline_color (Union[Color, ColorPalette]): The color or color palette to
+                use for outline. It is activated by setting outline_thickness to a value
+                greater than 0.
         """
         self.color: Union[Color, ColorPalette] = color
         self.base: int = base
@@ -1738,6 +1920,7 @@ class TriangleAnnotator(BaseAnnotator):
         self.position: Position = position
         self.color_lookup: ColorLookup = color_lookup
         self.outline_thickness: int = outline_thickness
+        self.outline_color: Union[Color, ColorPalette] = outline_color
 
     @ensure_cv2_image_for_annotation
     def annotate(
@@ -1778,6 +1961,7 @@ class TriangleAnnotator(BaseAnnotator):
         ![triangle-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/triangle-annotator-example.png)
         """
+        assert isinstance(scene, np.ndarray)
         xy = detections.get_anchors_coordinates(anchor=self.position)
         for detection_idx in range(len(detections)):
             color = resolve_color(
@@ -1800,8 +1984,20 @@ class TriangleAnnotator(BaseAnnotator):
 
             cv2.fillPoly(scene, [vertices], color.as_bgr())
             if self.outline_thickness:
+                outline_color = resolve_color(
+                    color=self.outline_color,
+                    detections=detections,
+                    detection_idx=detection_idx,
+                    color_lookup=self.color_lookup
+                    if custom_color_lookup is None
+                    else custom_color_lookup,
+                )
                 cv2.polylines(
-                    scene, [vertices], True, (0, 0, 0), thickness=self.outline_thickness
+                    scene,
+                    [vertices],
+                    True,
+                    outline_color.as_bgr(),
+                    thickness=self.outline_thickness,
                 )
         return scene
 
@@ -1824,7 +2020,7 @@ class RoundBoxAnnotator(BaseAnnotator):
             color (Union[Color, ColorPalette]): The color or color palette to use for
                 annotating detections.
             thickness (int): Thickness of the bounding box lines.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
             roundness (float): Percent of roundness for edges of bounding box.
                 Value must be float 0 < roundness <= 1.0
@@ -1878,7 +2074,7 @@ class RoundBoxAnnotator(BaseAnnotator):
         ![round-box-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/round-box-annotator-example-purple.png)
         """
-
+        assert isinstance(scene, np.ndarray)
         for detection_idx in range(len(detections)):
             x1, y1, x2, y2 = detections.xyxy[detection_idx].astype(int)
             color = resolve_color(
@@ -1951,7 +2147,7 @@ class PercentageBarAnnotator(BaseAnnotator):
         border_color: Color = Color.BLACK,
         position: Position = Position.TOP_CENTER,
         color_lookup: ColorLookup = ColorLookup.CLASS,
-        border_thickness: int = None,
+        border_thickness: Optional[int] = None,
     ):
         """
         Args:
@@ -1961,9 +2157,9 @@ class PercentageBarAnnotator(BaseAnnotator):
                 annotating detections.
             border_color (Color): The color of the border lines.
             position (Position): The anchor position of drawing the percentage bar.
-            color_lookup (str): Strategy for mapping colors to annotations.
+            color_lookup (ColorLookup): Strategy for mapping colors to annotations.
                 Options are `INDEX`, `CLASS`, `TRACK`.
-            border_thickness (int): The thickness of the border lines.
+            border_thickness (Optional[int]): The thickness of the border lines.
         """
         self.height: int = height
         self.width: int = width
@@ -2022,9 +2218,9 @@ class PercentageBarAnnotator(BaseAnnotator):
         ![percentage-bar-example](https://media.roboflow.com/
         supervision-annotator-examples/percentage-bar-annotator-example-purple.png)
         """
-        self.validate_custom_values(
-            custom_values=custom_values, detections_count=len(detections)
-        )
+        assert isinstance(scene, np.ndarray)
+        self.validate_custom_values(custom_values=custom_values, detections=detections)
+
         anchors = detections.get_anchors_coordinates(anchor=self.position)
         for detection_idx in range(len(detections)):
             anchor = anchors[detection_idx]
@@ -2035,11 +2231,11 @@ class PercentageBarAnnotator(BaseAnnotator):
             )
             border_width = border_coordinates[1][0] - border_coordinates[0][0]
 
-            value = (
-                custom_values[detection_idx]
-                if custom_values is not None
-                else detections.confidence[detection_idx]
-            )
+            if custom_values is not None:
+                value = custom_values[detection_idx]
+            else:
+                assert detections.confidence is not None  # MyPy type hint
+                value = detections.confidence[detection_idx]
 
             color = resolve_color(
                 color=self.color,
@@ -2099,15 +2295,23 @@ class PercentageBarAnnotator(BaseAnnotator):
 
     @staticmethod
     def validate_custom_values(
-        custom_values: Optional[Union[np.ndarray, List[float]]], detections_count: int
+        custom_values: Optional[Union[np.ndarray, List[float]]], detections: Detections
     ) -> None:
-        if custom_values is not None:
+        if custom_values is None:
+            if detections.confidence is None:
+                raise ValueError(
+                    "The provided detections do not contain confidence values. "
+                    "Please provide `custom_values` or ensure that the detections "
+                    "contain confidence values (e.g. by using a different model)."
+                )
+
+        else:
             if not isinstance(custom_values, (np.ndarray, list)):
                 raise TypeError(
                     "custom_values must be either a numpy array or a list of floats."
                 )
 
-            if len(custom_values) != detections_count:
+            if len(custom_values) != len(detections):
                 raise ValueError(
                     "The length of custom_values must match the number of detections."
                 )
@@ -2124,7 +2328,7 @@ class CropAnnotator(BaseAnnotator):
     def __init__(
         self,
         position: Position = Position.TOP_CENTER,
-        scale_factor: int = 2,
+        scale_factor: float = 2.0,
         border_color: Union[Color, ColorPalette] = ColorPalette.DEFAULT,
         border_thickness: int = 2,
         border_color_lookup: ColorLookup = ColorLookup.CLASS,
@@ -2133,7 +2337,7 @@ class CropAnnotator(BaseAnnotator):
         Args:
             position (Position): The anchor position for placing the cropped and scaled
                 part of the detection in the scene.
-            scale_factor (int): The factor by which to scale the cropped image part. A
+            scale_factor (float): The factor by which to scale the cropped image part. A
                 factor of 2, for example, would double the size of the cropped area,
                 allowing for a closer view of the detection.
             border_color (Union[Color, ColorPalette]): The color or color palette to
@@ -2143,7 +2347,7 @@ class CropAnnotator(BaseAnnotator):
                 annotations. Options are `INDEX`, `CLASS`, `TRACK`.
         """
         self.position: Position = position
-        self.scale_factor: int = scale_factor
+        self.scale_factor: float = scale_factor
         self.border_color: Union[Color, ColorPalette] = border_color
         self.border_thickness: int = border_thickness
         self.border_color_lookup: ColorLookup = border_color_lookup
@@ -2187,6 +2391,7 @@ class CropAnnotator(BaseAnnotator):
             )
             ```
         """
+        assert isinstance(scene, np.ndarray)
         crops = [
             crop_image(image=scene, xyxy=xyxy) for xyxy in detections.xyxy.astype(int)
         ]
@@ -2259,3 +2464,85 @@ class CropAnnotator(BaseAnnotator):
             )
         elif position == Position.BOTTOM_RIGHT:
             return (anchor_x, anchor_y), (anchor_x + width, anchor_y + height)
+
+
+class BackgroundOverlayAnnotator(BaseAnnotator):
+    """
+    A class for drawing a colored overlay on the background of an image outside
+    the region of detections.
+
+    If masks are provided, the background is colored outside the masks.
+    If masks are not provided, the background is colored outside the bounding boxes.
+
+    You can use the `force_box` parameter to force the annotator to use bounding boxes.
+
+    !!! warning
+
+        This annotator uses `sv.Detections.mask`.
+    """
+
+    def __init__(
+        self,
+        color: Color = Color.BLACK,
+        opacity: float = 0.5,
+        force_box: bool = False,
+    ):
+        """
+        Args:
+            color (Color): The color to use for annotating detections.
+            opacity (float): Opacity of the overlay mask. Must be between `0` and `1`.
+            force_box (bool): If `True`, forces the annotator to use bounding boxes when
+                masks are provided in the supplied sv.Detections.
+        """
+        self.color: Color = color
+        self.opacity = opacity
+        self.force_box = force_box
+
+    @ensure_cv2_image_for_annotation
+    def annotate(self, scene: ImageType, detections: Detections) -> ImageType:
+        """
+        Applies a colored overlay to the scene outside of the detected regions.
+
+        Args:
+            scene (ImageType): The image where masks will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
+            detections (Detections): Object detections to annotate.
+
+        Returns:
+            The annotated image, matching the type of `scene` (`numpy.ndarray`
+                or `PIL.Image.Image`)
+
+        Example:
+            ```python
+            import supervision as sv
+
+            image = ...
+            detections = sv.Detections(...)
+
+            background_overlay_annotator = sv.BackgroundOverlayAnnotator()
+            annotated_frame = background_overlay_annotator.annotate(
+                scene=image.copy(),
+                detections=detections
+            )
+            ```
+
+        ![background-overlay-annotator-example](https://media.roboflow.com/
+        supervision-annotator-examples/background-color-annotator-example-purple.png)
+        """
+        assert isinstance(scene, np.ndarray)
+        colored_mask = np.full_like(scene, self.color.as_bgr(), dtype=np.uint8)
+
+        cv2.addWeighted(
+            scene, 1 - self.opacity, colored_mask, self.opacity, 0, dst=colored_mask
+        )
+
+        if detections.mask is None or self.force_box:
+            for x1, y1, x2, y2 in detections.xyxy.astype(int):
+                colored_mask[y1:y2, x1:x2] = scene[y1:y2, x1:x2]
+        else:
+            for mask in detections.mask:
+                colored_mask[mask] = scene[mask]
+
+        np.copyto(scene, colored_mask)
+        return scene

supervision/annotators/utils.py

@@ -51,14 +51,17 @@ def resolve_color_idx(
         if detections.class_id is None:
             raise ValueError(
                 "Could not resolve color by class because "
-                "Detections do not have class_id"
+                "Detections do not have class_id. If using an annotator, "
+                "try setting color_lookup to sv.ColorLookup.INDEX or "
+                "sv.ColorLookup.TRACK."
             )
         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 "
-                "Detections do not have tracker_id"
+                "Detections do not have tracker_id. Did you call "
+                "tracker.update_with_detections(...) before annotating?"
             )
         return detections.tracker_id[detection_idx]
 

supervision/dataset/core.py

@@ -43,7 +43,10 @@ class BaseDataset(ABC):
 
     @abstractmethod
     def split(
-        self, split_ratio=0.8, random_state=None, shuffle: bool = True
+        self,
+        split_ratio: float = 0.8,
+        random_state: Optional[int] = None,
+        shuffle: bool = True,
     ) -> Tuple[BaseDataset, BaseDataset]:
         pass
 
@@ -174,18 +177,21 @@ class DetectionDataset(BaseDataset):
         return True
 
     def split(
-        self, split_ratio=0.8, random_state=None, shuffle: bool = True
+        self,
+        split_ratio: float = 0.8,
+        random_state: Optional[int] = None,
+        shuffle: bool = True,
     ) -> Tuple[DetectionDataset, DetectionDataset]:
         """
         Splits the dataset into two parts (training and testing)
             using the provided split_ratio.
 
         Args:
-            split_ratio (float, optional): The ratio of the training
+            split_ratio (float): The ratio of the training
                 set to the entire dataset.
-            random_state (int, optional): The seed for the random number generator.
+            random_state (Optional[int]): The seed for the random number generator.
                 This is used for reproducibility.
-            shuffle (bool, optional): Whether to shuffle the data before splitting.
+            shuffle (bool): Whether to shuffle the data before splitting.
 
         Returns:
             Tuple[DetectionDataset, DetectionDataset]: A tuple containing
@@ -396,7 +402,7 @@ class DetectionDataset(BaseDataset):
             images_directory_path (str): Path to the directory containing the images.
             annotations_directory_path (str): Path to the directory
                 containing the PASCAL VOC XML annotations.
-            force_masks (bool, optional): If True, forces masks to
+            force_masks (bool): If True, forces masks to
                 be loaded for all annotations, regardless of whether they are present.
 
         Returns:
@@ -455,10 +461,10 @@ class DetectionDataset(BaseDataset):
                 containing the YOLO annotation files.
             data_yaml_path (str): The path to the data
                 YAML file containing class information.
-            force_masks (bool, optional): If True, forces
+            force_masks (bool): If True, forces
                 masks to be loaded for all annotations,
                 regardless of whether they are present.
-            is_obb (bool, optional): If True, loads the annotations in OBB format.
+            is_obb (bool): If True, loads the annotations in OBB format.
                 OBB annotations are defined as `[class_id, x, y, x, y, x, y, x, y]`,
                 where pairs of [x, y] are box corners.
 
@@ -565,7 +571,7 @@ class DetectionDataset(BaseDataset):
             images_directory_path (str): The path to the
                 directory containing the images.
             annotations_path (str): The path to the json annotation files.
-            force_masks (bool, optional): If True,
+            force_masks (bool): If True,
                 forces masks to be loaded for all annotations,
                 regardless of whether they are present.
 
@@ -777,18 +783,21 @@ class ClassificationDataset(BaseDataset):
         return True
 
     def split(
-        self, split_ratio=0.8, random_state=None, shuffle: bool = True
+        self,
+        split_ratio: float = 0.8,
+        random_state: Optional[int] = None,
+        shuffle: bool = True,
     ) -> Tuple[ClassificationDataset, ClassificationDataset]:
         """
         Splits the dataset into two parts (training and testing)
             using the provided split_ratio.
 
         Args:
-            split_ratio (float, optional): The ratio of the training
+            split_ratio (float): The ratio of the training
                 set to the entire dataset.
-            random_state (int, optional): The seed for the
+            random_state (Optional[int]): The seed for the
                 random number generator. This is used for reproducibility.
-            shuffle (bool, optional): Whether to shuffle the data before splitting.
+            shuffle (bool): Whether to shuffle the data before splitting.
 
         Returns:
             Tuple[ClassificationDataset, ClassificationDataset]: A tuple containing

supervision/dataset/formats/pascal_voc.py

@@ -147,7 +147,7 @@ def load_pascal_voc_annotations(
         images_directory_path (str): The path to the directory containing the images.
         annotations_directory_path (str): The path to the directory containing the
             PASCAL VOC annotation files.
-        force_masks (bool, optional): If True, forces masks to be loaded for all
+        force_masks (bool): If True, forces masks to be loaded for all
             annotations, regardless of whether they are present.
 
     Returns:

supervision/dataset/formats/yolo.py

@@ -138,9 +138,9 @@ def load_yolo_annotations(
             containing the YOLO annotation files.
         data_yaml_path (str): The path to the data
             YAML file containing class information.
-        force_masks (bool, optional): If True, forces masks to be loaded
+        force_masks (bool): If True, forces masks to be loaded
             for all annotations, regardless of whether they are present.
-        is_obb (bool, optional): If True, loads the annotations in OBB format.
+        is_obb (bool): If True, loads the annotations in OBB format.
             OBB annotations are defined as `[class_id, x, y, x, y, x, y, x, y]`,
             where pairs of [x, y] are box corners.
 

supervision/detection/core.py

@@ -6,7 +6,10 @@ from typing import Any, Dict, Iterator, List, Optional, Tuple, Union
 
 import numpy as np
 
-from supervision.config import CLASS_NAME_DATA_FIELD, ORIENTED_BOX_COORDINATES
+from supervision.config import (
+    CLASS_NAME_DATA_FIELD,
+    ORIENTED_BOX_COORDINATES,
+)
 from supervision.detection.lmm import (
     LMM,
     from_florence_2,
@@ -18,6 +21,11 @@ from supervision.detection.overlap_filter import (
     box_non_max_suppression,
     mask_non_max_suppression,
 )
+from supervision.detection.tools.transformers import (
+    process_transformers_detection_result,
+    process_transformers_v4_segmentation_result,
+    process_transformers_v5_segmentation_result,
+)
 from supervision.detection.utils import (
     box_iou_batch,
     calculate_masks_centroids,
@@ -40,7 +48,7 @@ class Detections:
     The `sv.Detections` class in the Supervision library standardizes results from
     various object detection and segmentation models into a consistent format. This
     class simplifies data manipulation and filtering, providing a uniform API for
-    integration with Supervision [trackers](/trackers/), [annotators](/detection/annotators/), and [tools](/detection/tools/line_zone/).
+    integration with Supervision [trackers](/trackers/), [annotators](/latest/detection/annotators/), and [tools](/detection/tools/line_zone/).
 
     === "Inference"
 
@@ -244,11 +252,7 @@ class Detections:
             results = model(image)[0]
             detections = sv.Detections.from_ultralytics(results)
             ```
-
-        !!! tip
-
-            Class names values can be accessed using `detections["class_name"]`.
-        """  # noqa: E501 // docs
+        """
 
         if hasattr(ultralytics_results, "obb") and ultralytics_results.obb is not None:
             class_id = ultralytics_results.obb.cls.cpu().numpy().astype(int)
@@ -267,6 +271,14 @@ class Detections:
                 },
             )
 
+        if hasattr(ultralytics_results, "boxes") and ultralytics_results.boxes is None:
+            masks = extract_ultralytics_masks(ultralytics_results)
+            return cls(
+                xyxy=mask_to_xyxy(masks),
+                mask=masks,
+                class_id=np.arange(len(ultralytics_results)),
+            )
+
         class_id = ultralytics_results.boxes.cls.cpu().numpy().astype(int)
         class_names = np.array([ultralytics_results.names[i] for i in class_id])
         return cls(
@@ -347,7 +359,7 @@ class Detections:
             result = model(img)
             detections = sv.Detections.from_tensorflow(result)
             ```
-        """  # noqa: E501 // docs
+        """
 
         boxes = tensorflow_results["detection_boxes"][0].numpy()
         boxes[:, [0, 2]] *= resolution_wh[0]
@@ -422,7 +434,7 @@ class Detections:
             result = inference_detector(model, image)
             detections = sv.Detections.from_mmdetection(result)
             ```
-        """  # noqa: E501 // docs
+        """
 
         return cls(
             xyxy=mmdet_results.pred_instances.bboxes.cpu().numpy(),
@@ -438,15 +450,19 @@ class Detections:
         cls, transformers_results: dict, id2label: Optional[Dict[int, str]] = None
     ) -> Detections:
         """
-        Creates a Detections instance from object detection or segmentation
+        Creates a Detections instance from object detection or panoptic, semantic
+        and instance segmentation
         [Transformer](https://github.com/huggingface/transformers) inference result.
 
         Args:
-            transformers_results (dict): The output of Transformers model inference. A
-                dictionary containing the `scores`, `labels`, `boxes` and `masks` keys.
+            transformers_results (Union[dict, torch.Tensor]):  Inference results from
+                your Transformers model. This can be either a dictionary containing
+                valuable outputs like `scores`, `labels`, `boxes`, `masks`,
+                `segments_info`, and `segmentation`, or a `torch.Tensor` holding a
+                segmentation map where values represent class IDs.
             id2label (Optional[Dict[int, str]]): A dictionary mapping class IDs to
-                class names. If provided, the resulting Detections object will contain
-                `class_name` data field with the class names.
+                labels, typically part of the `transformers` model configuration. If
+                provided, the resulting dictionary will include class names.
 
         Returns:
             Detections: A new Detections object.
@@ -477,46 +493,45 @@ class Detections:
                 id2label=model.config.id2label
             )
             ```
+        """
 
-        !!! tip
+        if (
+            transformers_results.__class__.__name__ == "Tensor"
+            or "segmentation" in transformers_results
+        ):
+            return cls(
+                **process_transformers_v5_segmentation_result(
+                    transformers_results, id2label
+                )
+            )
 
-            Class names values can be accessed using `detections["class_name"]`.
-        """  # noqa: E501 // docs
+        if "masks" in transformers_results or "png_string" in transformers_results:
+            return cls(
+                **process_transformers_v4_segmentation_result(
+                    transformers_results, id2label
+                )
+            )
 
-        class_ids = transformers_results["labels"].cpu().detach().numpy().astype(int)
-        data = {}
-        if id2label is not None:
-            class_names = np.array([id2label[class_id] for class_id in class_ids])
-            data[CLASS_NAME_DATA_FIELD] = class_names
         if "boxes" in transformers_results:
             return cls(
-                xyxy=transformers_results["boxes"].cpu().detach().numpy(),
-                confidence=transformers_results["scores"].cpu().detach().numpy(),
-                class_id=class_ids,
-                data=data,
-            )
-        elif "masks" in transformers_results:
-            masks = transformers_results["masks"].cpu().detach().numpy().astype(bool)
-            return cls(
-                xyxy=mask_to_xyxy(masks),
-                mask=masks,
-                confidence=transformers_results["scores"].cpu().detach().numpy(),
-                class_id=class_ids,
-                data=data,
+                **process_transformers_detection_result(transformers_results, id2label)
             )
+
         else:
-            raise NotImplementedError(
-                "Only object detection and semantic segmentation results are supported."
+            raise ValueError(
+                "The provided Transformers results do not contain any valid fields."
+                " Expected fields are 'boxes', 'masks', 'segments_info' or"
+                " 'segmentation'."
             )
 
     @classmethod
-    def from_detectron2(cls, detectron2_results) -> Detections:
+    def from_detectron2(cls, detectron2_results: Any) -> Detections:
         """
         Create a Detections object from the
         [Detectron2](https://github.com/facebookresearch/detectron2) inference result.
 
         Args:
-            detectron2_results: The output of a
+            detectron2_results (Any): The output of a
                 Detectron2 model containing instances with prediction data.
 
         Returns:
@@ -583,10 +598,6 @@ class Detections:
             result = model.infer(image)[0]
             detections = sv.Detections.from_inference(result)
             ```
-
-        !!! tip
-
-            Class names values can be accessed using `detections["class_name"]`.
         """
         with suppress(AttributeError):
             roboflow_result = roboflow_result.dict(exclude_none=True, by_alias=True)
@@ -781,7 +792,7 @@ class Detections:
 
     @classmethod
     def from_lmm(
-        cls, lmm: Union[LMM, str], result: Union[str, dict], **kwargs
+        cls, lmm: Union[LMM, str], result: Union[str, dict], **kwargs: Any
     ) -> Detections:
         """
         Creates a Detections object from the given result string based on the specified
@@ -790,7 +801,7 @@ class Detections:
         Args:
             lmm (Union[LMM, str]): The type of LMM (Large Multimodal Model) to use.
             result (str): The result string containing the detection data.
-            **kwargs: Additional keyword arguments required by the specified LMM.
+            **kwargs (Any): Additional keyword arguments required by the specified LMM.
 
         Returns:
             Detections: A new Detections object.
@@ -842,6 +853,110 @@ class Detections:
 
         raise ValueError(f"Unsupported LMM: {lmm}")
 
+    @classmethod
+    def from_easyocr(cls, easyocr_results: list) -> Detections:
+        """
+        Create a Detections object from the
+        [EasyOCR](https://github.com/JaidedAI/EasyOCR) result.
+
+        Results are placed in the `data` field with the key `"class_name"`.
+
+        Args:
+            easyocr_results (List): The output Results instance from EasyOCR
+
+        Returns:
+            Detections: A new Detections object.
+
+        Example:
+            ```python
+            import supervision as sv
+            import easyocr
+
+            reader = easyocr.Reader(['en'])
+            results = reader.readtext(<SOURCE_IMAGE_PATH>)
+            detections = sv.Detections.from_easyocr(results)
+            detected_text = detections["class_name"]
+            ```
+        """
+        if len(easyocr_results) == 0:
+            return cls.empty()
+
+        bbox = np.array([result[0] for result in easyocr_results])
+        xyxy = np.hstack((np.min(bbox, axis=1), np.max(bbox, axis=1)))
+        confidence = np.array(
+            [
+                result[2] if len(result) > 2 and result[2] else 0
+                for result in easyocr_results
+            ]
+        )
+        ocr_text = np.array([result[1] for result in easyocr_results])
+
+        return cls(
+            xyxy=xyxy.astype(np.float32),
+            confidence=confidence.astype(np.float32),
+            data={
+                CLASS_NAME_DATA_FIELD: ocr_text,
+            },
+        )
+
+    @classmethod
+    def from_ncnn(cls, ncnn_results) -> Detections:
+        """
+        Creates a Detections instance from the
+        [ncnn](https://github.com/Tencent/ncnn) inference result.
+        Supports object detection models.
+
+        Arguments:
+            ncnn_results (dict): The output Results instance from ncnn.
+
+        Returns:
+            Detections: A new Detections object.
+
+        Example:
+            ```python
+            import cv2
+            from ncnn.model_zoo import get_model
+            import supervision as sv
+
+            image = cv2.imread(<SOURCE_IMAGE_PATH>)
+            model = get_model(
+                "yolov8s",
+                target_size=640
+                prob_threshold=0.5,
+                nms_threshold=0.45,
+                num_threads=4,
+                use_gpu=True,
+                )
+            result = model(image)
+            detections = sv.Detections.from_ncnn(result)
+            ```
+        """
+
+        xywh, confidences, class_ids = [], [], []
+
+        if len(ncnn_results) == 0:
+            return cls.empty()
+
+        for ncnn_result in ncnn_results:
+            rect = ncnn_result.rect
+            xywh.append(
+                [
+                    rect.x.astype(np.float32),
+                    rect.y.astype(np.float32),
+                    rect.w.astype(np.float32),
+                    rect.h.astype(np.float32),
+                ]
+            )
+
+            confidences.append(ncnn_result.prob)
+            class_ids.append(ncnn_result.label)
+
+        return cls(
+            xyxy=xywh_to_xyxy(np.array(xywh, dtype=np.float32)),
+            confidence=np.array(confidences, dtype=np.float32),
+            class_id=np.array(class_ids, dtype=int),
+        )
+
     @classmethod
     def empty(cls) -> Detections:
         """
@@ -1157,10 +1272,10 @@ class Detections:
         from a segmentation model, the IoU mask is applied. Otherwise, box IoU is used.
 
         Args:
-            threshold (float, optional): The intersection-over-union threshold
+            threshold (float): The intersection-over-union threshold
                 to use for non-maximum suppression. I'm the lower the value the more
                 restrictive the NMS becomes. Defaults to 0.5.
-            class_agnostic (bool, optional): Whether to perform class-agnostic
+            class_agnostic (bool): Whether to perform class-agnostic
                 non-maximum suppression. If True, the class_id of each detection
                 will be ignored. Defaults to False.
 
@@ -1212,9 +1327,9 @@ class Detections:
         Perform non-maximum merging on the current set of object detections.
 
         Args:
-            threshold (float, optional): The intersection-over-union threshold
+            threshold (float): The intersection-over-union threshold
                 to use for non-maximum merging. Defaults to 0.5.
-            class_agnostic (bool, optional): Whether to perform class-agnostic
+            class_agnostic (bool): Whether to perform class-agnostic
                 non-maximum merging. If True, the class_id of each detection
                 will be ignored. Defaults to False.
 

supervision/detection/line_zone.py

@@ -1,16 +1,23 @@
+import math
 import warnings
-from typing import Dict, Iterable, Optional, Tuple
+from collections import Counter
+from functools import lru_cache
+from typing import Any, Dict, Iterable, List, Literal, Optional, Tuple
 
 import cv2
 import numpy as np
 
+from supervision.config import CLASS_NAME_DATA_FIELD
 from supervision.detection.core import Detections
 from supervision.detection.utils import cross_product
 from supervision.draw.color import Color
-from supervision.draw.utils import draw_text
-from supervision.geometry.core import Point, Position, Vector
+from supervision.draw.utils import draw_rectangle, draw_text
+from supervision.geometry.core import Point, Position, Rect, Vector
+from supervision.utils.image import overlay_image
 from supervision.utils.internal import SupervisionWarnings
 
+TEXT_MARGIN = 10
+
 
 class LineZone:
     """
@@ -55,7 +62,7 @@ class LineZone:
         line_zone.in_count, line_zone.out_count
         # 7, 2
         ```
-    """  # noqa: E501 // docs
+    """
 
     def __init__(
         self,
@@ -81,11 +88,44 @@ class LineZone:
         self.vector = Vector(start=start, end=end)
         self.limits = self.calculate_region_of_interest_limits(vector=self.vector)
         self.tracker_state: Dict[str, bool] = {}
-        self.in_count: int = 0
-        self.out_count: int = 0
+        self._in_count_per_class: Counter = Counter()
+        self._out_count_per_class: Counter = Counter()
         self.triggering_anchors = triggering_anchors
         if not list(self.triggering_anchors):
             raise ValueError("Triggering anchors cannot be empty.")
+        self.class_id_to_name: Dict[int, str] = {}
+
+    @property
+    def in_count(self) -> int:
+        """
+        Number of objects that have crossed the line from
+        outside to inside.
+        """
+        return sum(self._in_count_per_class.values())
+
+    @property
+    def out_count(self) -> int:
+        """
+        Number of objects that have crossed the line from
+        inside to outside.
+        """
+        return sum(self._out_count_per_class.values())
+
+    @property
+    def in_count_per_class(self) -> Dict[int, int]:
+        """
+        Number of objects of each class that have crossed
+        the line from outside to inside.
+        """
+        return dict(self._in_count_per_class)
+
+    @property
+    def out_count_per_class(self) -> Dict[int, int]:
+        """
+        Number of objects of each class that have crossed the line
+        from inside to outside.
+        """
+        return dict(self._out_count_per_class)
 
     @staticmethod
     def calculate_region_of_interest_limits(vector: Vector) -> Tuple[Vector, Vector]:
@@ -170,7 +210,22 @@ class LineZone:
         has_any_left_trigger = np.any(triggers, axis=0)
         has_any_right_trigger = np.any(~triggers, axis=0)
         is_uniformly_triggered = ~(has_any_left_trigger & has_any_right_trigger)
-        for i, tracker_id in enumerate(detections.tracker_id):
+
+        class_ids = (
+            list(detections.class_id)
+            if detections.class_id is not None
+            else [None] * len(detections)
+        )
+        tracker_ids = list(detections.tracker_id)
+
+        if CLASS_NAME_DATA_FIELD in detections.data:
+            class_names = detections.data[CLASS_NAME_DATA_FIELD]
+            for class_id, class_name in zip(class_ids, class_names):
+                if class_id is None:
+                    class_name = "No class"
+                self.class_id_to_name[class_id] = class_name
+
+        for i, (class_ids, tracker_id) in enumerate(zip(class_ids, tracker_ids)):
             if not in_limits[i]:
                 continue
 
@@ -187,10 +242,10 @@ class LineZone:
 
             self.tracker_state[tracker_id] = tracker_state
             if tracker_state:
-                self.in_count += 1
+                self._in_count_per_class[class_ids] += 1
                 crossed_in[i] = True
             else:
-                self.out_count += 1
+                self._out_count_per_class[class_ids] += 1
                 crossed_out[i] = True
 
         return crossed_in, crossed_out
@@ -199,9 +254,9 @@ class LineZone:
 class LineZoneAnnotator:
     def __init__(
         self,
-        thickness: float = 2,
+        thickness: int = 2,
         color: Color = Color.WHITE,
-        text_thickness: float = 2,
+        text_thickness: int = 2,
         text_color: Color = Color.BLACK,
         text_scale: float = 0.5,
         text_offset: float = 1.5,
@@ -210,86 +265,67 @@ class LineZoneAnnotator:
         custom_out_text: Optional[str] = None,
         display_in_count: bool = True,
         display_out_count: bool = True,
+        display_text_box: bool = True,
+        text_orient_to_line: bool = False,
+        text_centered: bool = True,
     ):
         """
-        Initialize the LineCounterAnnotator object with default values.
+        A class for drawing the `LineZone` and its detected object count
+        on an image.
 
         Attributes:
-            thickness (float): The thickness of the line that will be drawn.
-            color (Color): The color of the line that will be drawn.
-            text_thickness (float): The thickness of the text that will be drawn.
-            text_color (Color): The color of the text that will be drawn.
-            text_scale (float): The scale of the text that will be drawn.
-            text_offset (float): The offset of the text that will be drawn.
-            text_padding (int): The padding of the text that will be drawn.
-            display_in_count (bool): Whether to display the in count or not.
-            display_out_count (bool): Whether to display the out count or not.
+            thickness (int): Line thickness.
+            color (Color): Line color.
+            text_thickness (int): Text thickness.
+            text_color (Color): Text color.
+            text_scale (float): Text scale.
+            text_offset (float): How far the text will be from the line.
+            text_padding (int): The empty space in the text box, surrounding the text.
+            custom_in_text (Optional[str]): Write something else instead of "in".
+            custom_out_text (Optional[str]): Write something else instead of "out".
+            display_in_count (bool): Pass `False` to hide the "in" count.
+            display_out_count (bool): Pass `False` to hide the "out" count.
+            display_text_box (bool): Pass `False` to hide the text background box.
+            text_orient_to_line (bool): ⭐ Match text orientation to the line.
+                Recommended to set to `True`.
+            text_centered (bool): Pass `False` to disable text centering. Useful
+                when the label overlaps something important.
 
         """
-        self.thickness: float = thickness
+        self.thickness: int = thickness
         self.color: Color = color
-        self.text_thickness: float = text_thickness
+        self.text_thickness: int = text_thickness
         self.text_color: Color = text_color
         self.text_scale: float = text_scale
         self.text_offset: float = text_offset
         self.text_padding: int = text_padding
-        self.custom_in_text: str = custom_in_text
-        self.custom_out_text: str = custom_out_text
+        self.in_text: str = custom_in_text if custom_in_text else "in"
+        self.out_text: str = custom_out_text if custom_out_text else "out"
         self.display_in_count: bool = display_in_count
         self.display_out_count: bool = display_out_count
-
-    def _annotate_count(
-        self,
-        frame: np.ndarray,
-        center_text_anchor: Point,
-        text: str,
-        is_in_count: bool,
-    ) -> None:
-        """This method is drawing the text on the frame.
-
-        Args:
-            frame (np.ndarray): The image on which the text will be drawn.
-            center_text_anchor: The center point that the text will be drawn.
-            text (str): The text that will be drawn.
-            is_in_count (bool): Whether to display the in count or out count.
-        """
-        _, text_height = cv2.getTextSize(
-            text, cv2.FONT_HERSHEY_SIMPLEX, self.text_scale, self.text_thickness
-        )[0]
-
-        if is_in_count:
-            center_text_anchor.y -= int(self.text_offset * text_height)
-        else:
-            center_text_anchor.y += int(self.text_offset * text_height)
-
-        draw_text(
-            scene=frame,
-            text=text,
-            text_anchor=center_text_anchor,
-            text_color=self.text_color,
-            text_scale=self.text_scale,
-            text_thickness=self.text_thickness,
-            text_padding=self.text_padding,
-            background_color=self.color,
-        )
+        self.display_text_box: bool = display_text_box
+        self.text_orient_to_line: bool = text_orient_to_line
+        self.text_centered: bool = text_centered
 
     def annotate(self, frame: np.ndarray, line_counter: LineZone) -> np.ndarray:
         """
-        Draws the line on the frame using the line_counter provided.
+        Draws the line on the frame using the line zone provided.
 
         Attributes:
             frame (np.ndarray): The image on which the line will be drawn.
-            line_counter (LineCounter): The line counter
+            line_counter (LineZone): The line zone
                 that will be used to draw the line.
 
         Returns:
-            np.ndarray: The image with the line drawn on it.
+            (np.ndarray): The image with the line drawn on it.
 
         """
+        line_start = line_counter.vector.start.as_xy_int_tuple()
+        line_end = line_counter.vector.end.as_xy_int_tuple()
         cv2.line(
             frame,
-            line_counter.vector.start.as_xy_int_tuple(),
-            line_counter.vector.end.as_xy_int_tuple(),
+            line_start,
+            line_end,
             self.color.as_bgr(),
             self.thickness,
             lineType=cv2.LINE_AA,
@@ -297,7 +333,7 @@ class LineZoneAnnotator:
         )
         cv2.circle(
             frame,
-            line_counter.vector.start.as_xy_int_tuple(),
+            line_start,
             radius=5,
             color=self.text_color.as_bgr(),
             thickness=-1,
@@ -305,40 +341,456 @@ class LineZoneAnnotator:
         )
         cv2.circle(
             frame,
-            line_counter.vector.end.as_xy_int_tuple(),
+            line_end,
             radius=5,
             color=self.text_color.as_bgr(),
             thickness=-1,
             lineType=cv2.LINE_AA,
         )
 
-        text_anchor = Vector(
-            start=line_counter.vector.start, end=line_counter.vector.end
+        in_text = f"{self.in_text}: {line_counter.in_count}"
+        out_text = f"{self.out_text}: {line_counter.out_count}"
+        line_angle_degrees = self._get_line_angle(line_counter)
+
+        for text, is_shown, is_in_count in [
+            (in_text, self.display_in_count, True),
+            (out_text, self.display_out_count, False),
+        ]:
+            if not is_shown:
+                continue
+
+            if line_angle_degrees == 0 or not self.text_orient_to_line:
+                self._draw_basic_label(
+                    frame=frame,
+                    line_center=line_counter.vector.center,
+                    text=text,
+                    is_in_count=is_in_count,
+                )
+            else:
+                self._draw_oriented_label(
+                    frame=frame,
+                    line_zone=line_counter,
+                    text=text,
+                    is_in_count=is_in_count,
+                )
+
+        return frame
+
+    def _get_line_angle(self, line_zone: LineZone) -> float:
+        """
+        Calculate the line counter angle (in degrees).
+
+        Args:
+            line_zone (LineZone): The line zone object.
+
+        Returns:
+            (float): Line counter angle, in degrees.
+        """
+        start_point = line_zone.vector.start.as_xy_int_tuple()
+        end_point = line_zone.vector.end.as_xy_int_tuple()
+
+        delta_x = end_point[0] - start_point[0]
+        delta_y = end_point[1] - start_point[1]
+
+        if delta_x == 0:
+            line_angle = 90.0
+            line_angle += 180 if delta_y < 0 else 0
+        else:
+            line_angle = math.degrees(math.atan(delta_y / delta_x))
+            line_angle += 180 if delta_x < 0 else 0
+
+        return line_angle
+
+    def _calculate_anchor_in_frame(
+        self,
+        line_zone: LineZone,
+        text_width: int,
+        text_height: int,
+        is_in_count: bool,
+        label_dimension: int,
+    ) -> Tuple[int, int]:
+        """
+        Calculate insertion anchor in frame to position the center of the count image.
+
+        Args:
+            line_zone (LineZone): The line counter object used for counting.
+            text_width (int): Text width.
+            text_height (int): Text height.
+            is_in_count (bool): Whether the count should be placed over or below line.
+            label_dimension (int): Size of the label image. Assumes the
+                label is rectangular.
+
+        Returns:
+            (Tuple[int, int]): xy, point in an image where the label will be placed.
+        """
+        line_angle = self._get_line_angle(line_zone)
+
+        if self.text_centered:
+            mid_point = Vector(
+                start=line_zone.vector.start, end=line_zone.vector.end
+            ).center.as_xy_int_tuple()
+            anchor = list(mid_point)
+        else:
+            end_point = line_zone.vector.end.as_xy_int_tuple()
+            anchor = list(end_point)
+
+            move_along_x = int(
+                math.cos(math.radians(line_angle))
+                * (text_width / 2 + self.text_padding)
+            )
+            move_along_y = int(
+                math.sin(math.radians(line_angle))
+                * (text_width / 2 + self.text_padding)
+            )
+
+            anchor[0] -= move_along_x
+            anchor[1] -= move_along_y
+
+        move_perpendicular_x = int(
+            math.sin(math.radians(line_angle)) * (self.text_offset * text_height)
+        )
+        move_perpendicular_y = int(
+            math.cos(math.radians(line_angle)) * (self.text_offset * text_height)
         )
 
-        if self.display_in_count:
-            in_text = (
-                f"{self.custom_in_text}: {line_counter.in_count}"
-                if self.custom_in_text is not None
-                else f"in: {line_counter.in_count}"
-            )
-            self._annotate_count(
-                frame=frame,
-                center_text_anchor=text_anchor.center,
-                text=in_text,
-                is_in_count=True,
+        if is_in_count:
+            anchor[0] += move_perpendicular_x
+            anchor[1] -= move_perpendicular_y
+        else:
+            anchor[0] -= move_perpendicular_x
+            anchor[1] += move_perpendicular_y
+
+        x1 = max(anchor[0] - label_dimension // 2, 0)
+        y1 = max(anchor[1] - label_dimension // 2, 0)
+
+        return x1, y1
+
+    def _draw_basic_label(
+        self,
+        frame: np.ndarray,
+        line_center: Point,
+        text: str,
+        is_in_count: bool,
+    ) -> np.ndarray:
+        """
+        Draw the count label on the frame. For example: "out: 7".
+        The label contains horizontal text and is not rotated.
+
+        Args:
+            frame (np.ndarray): The entire scene, on which the label will be placed.
+            line_center (Point): The center of the line zone.
+            text (str): The text that will be drawn.
+            is_in_count (bool): Whether to display the in count (above line)
+                or out count (below line).
+
+        Returns:
+            (np.ndarray): The scene with the label drawn on it.
+        """
+        _, text_height = cv2.getTextSize(
+            text, cv2.FONT_HERSHEY_SIMPLEX, self.text_scale, self.text_thickness
+        )[0]
+
+        if is_in_count:
+            line_center.y -= int(self.text_offset * text_height)
+        else:
+            line_center.y += int(self.text_offset * text_height)
+
+        draw_text(
+            scene=frame,
+            text=text,
+            text_anchor=line_center,
+            text_color=self.text_color,
+            text_scale=self.text_scale,
+            text_thickness=self.text_thickness,
+            text_padding=self.text_padding,
+            background_color=self.color if self.display_text_box else None,
+        )
+
+        return frame
+
+    def _draw_oriented_label(
+        self,
+        frame: np.ndarray,
+        line_zone: LineZone,
+        text: str,
+        is_in_count: bool,
+    ) -> np.ndarray:
+        """
+        Draw the count label on the frame. For example: "out: 7".
+        The label is oriented to match the line angle.
+
+        Args:
+            frame (np.ndarray): The entire scene, on which the label will be placed.
+            line_zone (LineZone): The line zone responsible for counting
+                objects crossing it.
+            text (str): The text that will be drawn.
+            is_in_count (bool): Whether to display the in count (above line)
+                or out count (below line).
+
+        Returns:
+            (np.ndarray): The scene with the label drawn on it.
+        """
+
+        line_angle_degrees = self._get_line_angle(line_zone)
+        label_image = self._make_label_image(
+            text,
+            text_scale=self.text_scale,
+            text_thickness=self.text_thickness,
+            text_padding=self.text_padding,
+            text_color=self.text_color,
+            text_box_show=self.display_text_box,
+            text_box_color=self.color,
+            line_angle_degrees=line_angle_degrees,
+        )
+        assert label_image.shape[0] == label_image.shape[1]
+
+        text_width, text_height = cv2.getTextSize(
+            text, cv2.FONT_HERSHEY_SIMPLEX, self.text_scale, self.text_thickness
+        )[0]
+
+        label_anchor = self._calculate_anchor_in_frame(
+            line_zone=line_zone,
+            text_width=text_width,
+            text_height=text_height,
+            is_in_count=is_in_count,
+            label_dimension=label_image.shape[0],
+        )
+
+        frame = overlay_image(frame, label_image, label_anchor)
+
+        return frame
+
+    @staticmethod
+    @lru_cache(maxsize=32)
+    def _make_label_image(
+        text: str,
+        *,
+        text_scale: float,
+        text_thickness: int,
+        text_padding: int,
+        text_color: Color,
+        text_box_show: bool,
+        text_box_color: Color,
+        line_angle_degrees: float,
+    ) -> np.ndarray:
+        """
+        Create the small text box displaying line zone count. E.g. "out: 7".
+
+        Args:
+            text (str): The text to display.
+            text_scale (float): The scale of the text.
+            text_thickness (int): The thickness of the text.
+            text_padding (int): The padding around the text.
+            text_color (Color): The color of the text.
+            text_box_show (bool): Whether to display the text box.
+            text_box_color (Color): The color of the text box.
+            line_angle_degrees (float): The angle of the line in degrees.
+
+        Returns:
+            (np.ndarray): The label of shape (H, W, 4), in BGRA format.
+        """
+        text_width, text_height = cv2.getTextSize(
+            text, cv2.FONT_HERSHEY_SIMPLEX, text_scale, text_thickness
+        )[0]
+
+        annotation_dim = int((max(text_width, text_height) + text_padding * 2) * 1.5)
+        annotation_shape = (annotation_dim, annotation_dim)
+        annotation_center = Point(annotation_dim // 2, annotation_dim // 2)
+
+        annotation = np.zeros((*annotation_shape, 3), dtype=np.uint8)
+        annotation_alpha = np.zeros((*annotation_shape, 1), dtype=np.uint8)
+
+        text_args: Dict[str, Any] = dict(
+            text=text,
+            text_anchor=annotation_center,
+            text_scale=text_scale,
+            text_thickness=text_thickness,
+            text_padding=text_padding,
+        )
+        draw_text(
+            scene=annotation,
+            text_color=text_color,
+            background_color=text_box_color if text_box_show else None,
+            **text_args,
+        )
+        draw_text(
+            scene=annotation_alpha,
+            text_color=Color.WHITE,
+            background_color=Color.WHITE if text_box_show else None,
+            **text_args,
+        )
+        annotation = np.dstack((annotation, annotation_alpha))
+
+        # Make sure text is displayed upright
+        if 90 < line_angle_degrees % 360 < 270:
+            annotation = cv2.flip(annotation, flipCode=-1).astype(np.uint8)
+
+        rotation_angle = -line_angle_degrees
+        rotation_matrix = cv2.getRotationMatrix2D(
+            annotation_center.as_xy_float_tuple(), rotation_angle, scale=1
+        )
+        annotation = cv2.warpAffine(annotation, rotation_matrix, annotation_shape)
+
+        return annotation
+
+
+class LineZoneAnnotatorMulticlass:
+    def __init__(
+        self,
+        *,
+        table_position: Literal[
+            Position.TOP_LEFT,
+            Position.TOP_RIGHT,
+            Position.BOTTOM_LEFT,
+            Position.BOTTOM_RIGHT,
+        ] = Position.TOP_RIGHT,
+        table_color: Color = Color.WHITE,
+        table_margin: int = 10,
+        table_padding: int = 10,
+        table_max_width: int = 400,
+        text_color: Color = Color.BLACK,
+        text_scale: float = 0.75,
+        text_thickness: int = 1,
+        force_draw_class_ids: bool = False,
+    ):
+        """
+        Draw a table showing how many items of each class crossed each line.
+
+        Args:
+            table_position (Position): The position of the table.
+            table_color (Color): The color of the table.
+            table_margin (int): The margin of the table from the image border.
+            table_padding (int): The padding of the table.
+            table_max_width (int): The maximum width of the table.
+            text_color (Color): The color of the text.
+            text_scale (float): The scale of the text.
+            text_thickness (int): The thickness of the text.
+            force_draw_class_ids (bool): Instead of writing the class names,
+                on the table, write the class IDs. E.g. instead of `person: 6`,
+                write `0: 6`.
+        """
+        if table_position not in {
+            Position.TOP_LEFT,
+            Position.TOP_RIGHT,
+            Position.BOTTOM_LEFT,
+            Position.BOTTOM_RIGHT,
+        }:
+            raise ValueError(
+                "Invalid table position. Supported values are:"
+                " TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT."
             )
 
-        if self.display_out_count:
-            out_text = (
-                f"{self.custom_out_text}: {line_counter.out_count}"
-                if self.custom_out_text is not None
-                else f"out: {line_counter.out_count}"
-            )
-            self._annotate_count(
-                frame=frame,
-                center_text_anchor=text_anchor.center,
-                text=out_text,
-                is_in_count=False,
+        self.table_position = table_position
+        self.table_color = table_color
+        self.table_margin = table_margin
+        self.table_padding = table_padding
+        self.table_max_width = table_max_width
+        self.text_color = text_color
+        self.text_scale = text_scale
+        self.text_thickness = text_thickness
+        self.force_draw_class_ids = force_draw_class_ids
+
+    def annotate(
+        self,
+        frame: np.ndarray,
+        line_zones: List[LineZone],
+        line_zone_labels: Optional[List[str]] = None,
+    ) -> np.ndarray:
+        """
+        Draws a table with the number of objects of each class that crossed each line.
+
+        Attributes:
+            frame (np.ndarray): The image on which the table will be drawn.
+            line_zones (List[LineZone]): The line zones to be annotated.
+            line_zone_labels (Optional[List[str]]): The labels, one for each
+                line zone. If not provided, the default labels will be used.
+
+        Returns:
+            (np.ndarray): The image with the table drawn on it.
+
+        """
+        if line_zone_labels is None:
+            line_zone_labels = [f"Line {i + 1}:" for i in range(len(line_zones))]
+        if len(line_zones) != len(line_zone_labels):
+            raise ValueError("The number of line zones and their labels must match.")
+
+        text_lines = ["Line Crossings:"]
+        for line_zone, line_zone_label in zip(line_zones, line_zone_labels):
+            text_lines.append(line_zone_label)
+            class_id_to_name = line_zone.class_id_to_name
+
+            for direction, count_per_class in [
+                ("In", line_zone.in_count_per_class),
+                ("Out", line_zone.out_count_per_class),
+            ]:
+                if not count_per_class:
+                    continue
+
+                text_lines.append(f" {direction}:")
+                for class_id, count in count_per_class.items():
+                    class_name = (
+                        class_id_to_name.get(class_id, str(class_id))
+                        if not self.force_draw_class_ids
+                        else str(class_id)
+                    )
+                    text_lines.append(f"  {class_name}: {count}")
+
+        table_width, table_height = 0, 0
+        for line in text_lines:
+            text_width, text_height = cv2.getTextSize(
+                line, cv2.FONT_HERSHEY_SIMPLEX, self.text_scale, self.text_thickness
+            )[0]
+            text_height += TEXT_MARGIN
+            table_width = max(table_width, text_width)
+            table_height += text_height
+
+        table_width += 2 * self.table_padding
+        table_height += 2 * self.table_padding
+        table_max_height = frame.shape[0] - 2 * self.table_margin
+        table_height = min(table_height, table_max_height)
+        table_width = min(table_width, self.table_max_width)
+
+        position_map = {
+            Position.TOP_LEFT: (self.table_margin, self.table_margin),
+            Position.TOP_RIGHT: (
+                frame.shape[1] - table_width - self.table_margin,
+                self.table_margin,
+            ),
+            Position.BOTTOM_LEFT: (
+                self.table_margin,
+                frame.shape[0] - table_height - self.table_margin,
+            ),
+            Position.BOTTOM_RIGHT: (
+                frame.shape[1] - table_width - self.table_margin,
+                frame.shape[0] - table_height - self.table_margin,
+            ),
+        }
+        table_x1, table_y1 = position_map[self.table_position]
+
+        table_rect = Rect(
+            x=table_x1, y=table_y1, width=table_width, height=table_height
+        )
+        frame = draw_rectangle(
+            scene=frame, rect=table_rect, color=self.table_color, thickness=-1
+        )
+
+        for i, line in enumerate(text_lines):
+            _, text_height = cv2.getTextSize(
+                line, cv2.FONT_HERSHEY_SIMPLEX, self.text_scale, self.text_thickness
+            )[0]
+            text_height += TEXT_MARGIN
+            anchor_x = table_x1 + self.table_padding
+            anchor_y = table_y1 + self.table_padding + (i + 1) * text_height
+
+            cv2.putText(
+                img=frame,
+                text=line,
+                org=(anchor_x, anchor_y),
+                fontFace=cv2.FONT_HERSHEY_SIMPLEX,
+                fontScale=self.text_scale,
+                color=self.text_color.as_bgr(),
+                thickness=self.text_thickness,
+                lineType=cv2.LINE_AA,
             )
+
         return frame

supervision/detection/lmm.py

@@ -113,7 +113,7 @@ def from_florence_2(
             oriented bounding boxes.
     """
     assert len(result) == 1, f"Expected result with a single element. Got: {result}"
-    task = list(result.keys())[0]
+    task = next(iter(result.keys()))
     if task not in SUPPORTED_TASKS_FLORENCE_2:
         raise ValueError(
             f"{task} not supported. Supported tasks are: {SUPPORTED_TASKS_FLORENCE_2}"

supervision/detection/overlap_filter.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from enum import Enum
 from typing import List, Union
 
@@ -53,9 +55,9 @@ def mask_non_max_suppression(
         masks (np.ndarray): A 3D array of binary masks corresponding to the predictions.
             Shape: `(N, H, W)`, where N is the number of predictions, and H, W are the
             dimensions of each mask.
-        iou_threshold (float, optional): The intersection-over-union threshold
+        iou_threshold (float): The intersection-over-union threshold
             to use for non-maximum suppression.
-        mask_dimension (int, optional): The dimension to which the masks should be
+        mask_dimension (int): The dimension to which the masks should be
             resized before computing IOU values. Defaults to 640.
 
     Returns:
@@ -64,7 +66,7 @@ def mask_non_max_suppression(
 
     Raises:
         AssertionError: If `iou_threshold` is not within the closed
-        range from `0` to `1`.
+            range from `0` to `1`.
     """
     assert 0 <= iou_threshold <= 1, (
         "Value of `iou_threshold` must be in the closed range from 0 to 1, "
@@ -101,7 +103,7 @@ def box_non_max_suppression(
         predictions (np.ndarray): An array of object detection predictions in
             the format of `(x_min, y_min, x_max, y_max, score)`
             or `(x_min, y_min, x_max, y_max, score, class)`.
-        iou_threshold (float, optional): The intersection-over-union threshold
+        iou_threshold (float): The intersection-over-union threshold
             to use for non-maximum suppression.
 
     Returns:
@@ -156,7 +158,7 @@ def group_overlapping_boxes(
         predictions (npt.NDArray[np.float64]): An array of shape `(n, 5)` containing
             the bounding boxes coordinates in format `[x1, y1, x2, y2]`
             and the confidence scores.
-        iou_threshold (float, optional): The intersection-over-union threshold
+        iou_threshold (float): The intersection-over-union threshold
             to use for non-maximum suppression. Defaults to 0.5.
 
     Returns:
@@ -181,7 +183,7 @@ def group_overlapping_boxes(
         ious = ious.flatten()
 
         above_threshold = ious >= iou_threshold
-        merge_group = [idx] + np.flip(order[above_threshold]).tolist()
+        merge_group = [idx, *np.flip(order[above_threshold]).tolist()]
         merge_groups.append(merge_group)
         order = order[~above_threshold]
     return merge_groups
@@ -200,7 +202,7 @@ def box_non_max_merge(
             containing the bounding boxes coordinates in format `[x1, y1, x2, y2]`,
             the confidence scores and class_ids. Omit class_id column to allow
             detections of different classes to be merged.
-        iou_threshold (float, optional): The intersection-over-union threshold
+        iou_threshold (float): The intersection-over-union threshold
             to use for non-maximum suppression. Defaults to 0.5.
 
     Returns:
@@ -248,16 +250,21 @@ class OverlapFilter(Enum):
     NON_MAX_SUPPRESSION = "non_max_suppression"
     NON_MAX_MERGE = "non_max_merge"
 
+    @classmethod
+    def list(cls):
+        return list(map(lambda c: c.value, cls))
 
-def validate_overlap_filter(
-    strategy: Union[OverlapFilter, str],
-) -> OverlapFilter:
-    if isinstance(strategy, str):
-        try:
-            strategy = OverlapFilter(strategy.lower())
-        except ValueError:
-            raise ValueError(
-                f"Invalid strategy value: {strategy}. Must be one of "
-                f"{[e.value for e in OverlapFilter]}"
-            )
-    return strategy
+    @classmethod
+    def from_value(cls, value: Union[OverlapFilter, str]) -> OverlapFilter:
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, str):
+            value = value.lower()
+            try:
+                return cls(value)
+            except ValueError:
+                raise ValueError(f"Invalid value: {value}. Must be one of {cls.list()}")
+        raise ValueError(
+            f"Invalid value type: {type(value)}. Must be an instance of "
+            f"{cls.__name__} or str."
+        )

supervision/detection/tools/csv_sink.py

@@ -48,7 +48,7 @@ class CSVSink:
                 detections = sv.Detections.from_ultralytics(result)
                 sink.append(detections, custom_data={'<CUSTOM_LABEL>':'<CUSTOM_DATA>'})
         ```
-    """  # noqa: E501 // docs
+    """
 
     def __init__(self, file_name: str = "output.csv") -> None:
         """
@@ -104,7 +104,7 @@ class CSVSink:
 
     @staticmethod
     def parse_detection_data(
-        detections: Detections, custom_data: Dict[str, Any] = None
+        detections: Detections, custom_data: Optional[Dict[str, Any]] = None
     ) -> List[Dict[str, Any]]:
         parsed_rows = []
         for i in range(len(detections.xyxy)):
@@ -137,7 +137,7 @@ class CSVSink:
         return parsed_rows
 
     def append(
-        self, detections: Detections, custom_data: Dict[str, Any] = None
+        self, detections: Detections, custom_data: Optional[Dict[str, Any]] = None
     ) -> None:
         """
         Append detection data to the CSV file.

supervision/detection/tools/inference_slicer.py

@@ -4,11 +4,15 @@ from typing import Callable, Optional, Tuple, Union
 
 import numpy as np
 
+from supervision.config import ORIENTED_BOX_COORDINATES
 from supervision.detection.core import Detections
-from supervision.detection.overlap_filter import OverlapFilter, validate_overlap_filter
-from supervision.detection.utils import move_boxes, move_masks
+from supervision.detection.overlap_filter import OverlapFilter
+from supervision.detection.utils import move_boxes, move_masks, move_oriented_boxes
 from supervision.utils.image import crop_image
-from supervision.utils.internal import SupervisionWarnings
+from supervision.utils.internal import (
+    SupervisionWarnings,
+    warn_deprecated,
+)
 
 
 def move_detections(
@@ -28,6 +32,10 @@ def move_detections(
         (sv.Detections) repositioned Detections object.
     """
     detections.xyxy = move_boxes(xyxy=detections.xyxy, offset=offset)
+    if ORIENTED_BOX_COORDINATES in detections.data:
+        detections.data[ORIENTED_BOX_COORDINATES] = move_oriented_boxes(
+            xyxyxyxy=detections.data[ORIENTED_BOX_COORDINATES], offset=offset
+        )
     if detections.mask is not None:
         if resolution_wh is None:
             raise ValueError(
@@ -49,11 +57,18 @@ class InferenceSlicer:
     slice, and then merging the detections.
 
     Args:
-        slice_wh (Tuple[int, int]): Dimensions of each slice in the format
-            `(width, height)`.
-        overlap_ratio_wh (Tuple[float, float]): Overlap ratio between consecutive
-            slices in the format `(width_ratio, height_ratio)`.
-        overlap_filter_strategy (Union[OverlapFilter, str]): Strategy for
+        slice_wh (Tuple[int, int]): Dimensions of each slice measured in pixels. The
+            tuple should be in the format `(width, height)`.
+        overlap_ratio_wh (Optional[Tuple[float, float]]): [⚠️ Deprecated: please set
+                to `None` and use `overlap_wh`] A tuple representing the
+            desired overlap ratio for width and height between consecutive slices.
+            Each value should be in the range [0, 1), where 0 means no overlap and
+            a value close to 1 means high overlap.
+        overlap_wh (Optional[Tuple[int, int]]): A tuple representing the desired
+            overlap for width and height between consecutive slices measured in pixels.
+            Each value should be greater than or equal to 0. Takes precedence over
+            `overlap_ratio_wh`.
+        overlap_filter (Union[OverlapFilter, str]): Strategy for
             filtering or merging overlapping detections in slices.
         iou_threshold (float): Intersection over Union (IoU) threshold
             used when filtering by overlap.
@@ -72,19 +87,26 @@ class InferenceSlicer:
         self,
         callback: Callable[[np.ndarray], Detections],
         slice_wh: Tuple[int, int] = (320, 320),
-        overlap_ratio_wh: Tuple[float, float] = (0.2, 0.2),
-        overlap_filter_strategy: Union[
-            OverlapFilter, str
-        ] = OverlapFilter.NON_MAX_SUPPRESSION,
+        overlap_ratio_wh: Optional[Tuple[float, float]] = (0.2, 0.2),
+        overlap_wh: Optional[Tuple[int, int]] = None,
+        overlap_filter: Union[OverlapFilter, str] = OverlapFilter.NON_MAX_SUPPRESSION,
         iou_threshold: float = 0.5,
         thread_workers: int = 1,
     ):
-        overlap_filter_strategy = validate_overlap_filter(overlap_filter_strategy)
+        if overlap_ratio_wh is not None:
+            warn_deprecated(
+                "`overlap_ratio_wh` in `InferenceSlicer.__init__` is deprecated and "
+                "will be removed in `supervision-0.27.0`. Please manually set it to "
+                "`None` and use `overlap_wh` instead."
+            )
+
+        self._validate_overlap(overlap_ratio_wh, overlap_wh)
+        self.overlap_ratio_wh = overlap_ratio_wh
+        self.overlap_wh = overlap_wh
 
         self.slice_wh = slice_wh
-        self.overlap_ratio_wh = overlap_ratio_wh
         self.iou_threshold = iou_threshold
-        self.overlap_filter_strategy = overlap_filter_strategy
+        self.overlap_filter = OverlapFilter.from_value(overlap_filter)
         self.callback = callback
         self.thread_workers = thread_workers
 
@@ -129,6 +151,7 @@ class InferenceSlicer:
             resolution_wh=resolution_wh,
             slice_wh=self.slice_wh,
             overlap_ratio_wh=self.overlap_ratio_wh,
+            overlap_wh=self.overlap_wh,
         )
 
         with ThreadPoolExecutor(max_workers=self.thread_workers) as executor:
@@ -139,15 +162,15 @@ class InferenceSlicer:
                 detections_list.append(future.result())
 
         merged = Detections.merge(detections_list=detections_list)
-        if self.overlap_filter_strategy == OverlapFilter.NONE:
+        if self.overlap_filter == OverlapFilter.NONE:
             return merged
-        elif self.overlap_filter_strategy == OverlapFilter.NON_MAX_SUPPRESSION:
+        elif self.overlap_filter == OverlapFilter.NON_MAX_SUPPRESSION:
             return merged.with_nms(threshold=self.iou_threshold)
-        elif self.overlap_filter_strategy == OverlapFilter.NON_MAX_MERGE:
+        elif self.overlap_filter == OverlapFilter.NON_MAX_MERGE:
             return merged.with_nmm(threshold=self.iou_threshold)
         else:
             warnings.warn(
-                f"Invalid overlap filter strategy: {self.overlap_filter_strategy}",
+                f"Invalid overlap filter strategy: {self.overlap_filter}",
                 category=SupervisionWarnings,
             )
             return merged
@@ -177,7 +200,8 @@ class InferenceSlicer:
     def _generate_offset(
         resolution_wh: Tuple[int, int],
         slice_wh: Tuple[int, int],
-        overlap_ratio_wh: Tuple[float, float],
+        overlap_ratio_wh: Optional[Tuple[float, float]],
+        overlap_wh: Optional[Tuple[int, int]],
     ) -> np.ndarray:
         """
         Generate offset coordinates for slicing an image based on the given resolution,
@@ -186,12 +210,15 @@ class InferenceSlicer:
         Args:
             resolution_wh (Tuple[int, int]): A tuple representing the width and height
                 of the image to be sliced.
-            slice_wh (Tuple[int, int]): A tuple representing the desired width and
-                height of each slice.
-            overlap_ratio_wh (Tuple[float, float]): A tuple representing the desired
-                overlap ratio for width and height between consecutive slices. Each
-                value should be in the range [0, 1), where 0 means no overlap and a
-                value close to 1 means high overlap.
+            slice_wh (Tuple[int, int]): Dimensions of each slice measured in pixels. The
+            tuple should be in the format `(width, height)`.
+            overlap_ratio_wh (Optional[Tuple[float, float]]): A tuple representing the
+                desired overlap ratio for width and height between consecutive slices.
+                Each value should be in the range [0, 1), where 0 means no overlap and
+                a value close to 1 means high overlap.
+            overlap_wh (Optional[Tuple[int, int]]): A tuple representing the desired
+                overlap for width and height between consecutive slices measured in
+                pixels. Each value should be greater than or equal to 0.
 
         Returns:
             np.ndarray: An array of shape `(n, 4)` containing coordinates for each
@@ -206,10 +233,19 @@ class InferenceSlicer:
         """
         slice_width, slice_height = slice_wh
         image_width, image_height = resolution_wh
-        overlap_ratio_width, overlap_ratio_height = overlap_ratio_wh
+        overlap_width = (
+            overlap_wh[0]
+            if overlap_wh is not None
+            else int(overlap_ratio_wh[0] * slice_width)
+        )
+        overlap_height = (
+            overlap_wh[1]
+            if overlap_wh is not None
+            else int(overlap_ratio_wh[1] * slice_height)
+        )
 
-        width_stride = slice_width - int(overlap_ratio_width * slice_width)
-        height_stride = slice_height - int(overlap_ratio_height * slice_height)
+        width_stride = slice_width - overlap_width
+        height_stride = slice_height - overlap_height
 
         ws = np.arange(0, image_width, width_stride)
         hs = np.arange(0, image_height, height_stride)
@@ -221,3 +257,32 @@ class InferenceSlicer:
         offsets = np.stack([xmin, ymin, xmax, ymax], axis=-1).reshape(-1, 4)
 
         return offsets
+
+    @staticmethod
+    def _validate_overlap(
+        overlap_ratio_wh: Optional[Tuple[float, float]],
+        overlap_wh: Optional[Tuple[int, int]],
+    ) -> None:
+        if overlap_ratio_wh is not None and overlap_wh is not None:
+            raise ValueError(
+                "Both `overlap_ratio_wh` and `overlap_wh` cannot be provided. "
+                "Please provide only one of them."
+            )
+        if overlap_ratio_wh is None and overlap_wh is None:
+            raise ValueError(
+                "Either `overlap_ratio_wh` or `overlap_wh` must be provided. "
+                "Please provide one of them."
+            )
+
+        if overlap_ratio_wh is not None:
+            if not (0 <= overlap_ratio_wh[0] < 1 and 0 <= overlap_ratio_wh[1] < 1):
+                raise ValueError(
+                    "Overlap ratios must be in the range [0, 1). "
+                    f"Received: {overlap_ratio_wh}"
+                )
+        if overlap_wh is not None:
+            if not (overlap_wh[0] >= 0 and overlap_wh[1] >= 0):
+                raise ValueError(
+                    "Overlap values must be greater than or equal to 0. "
+                    f"Received: {overlap_wh}"
+                )

supervision/detection/tools/json_sink.py

@@ -38,7 +38,7 @@ class JSONSink:
                 detections = sv.Detections.from_ultralytics(result)
                 sink.append(detections, custom_data={'<CUSTOM_LABEL>':'<CUSTOM_DATA>'})
         ```
-    """  # noqa: E501 // docs
+    """
 
     def __init__(self, file_name: str = "output.json") -> None:
         """
@@ -92,7 +92,7 @@ class JSONSink:
 
     @staticmethod
     def parse_detection_data(
-        detections: Detections, custom_data: Dict[str, Any] = None
+        detections: Detections, custom_data: Optional[Dict[str, Any]] = None
     ) -> List[Dict[str, Any]]:
         parsed_rows = []
         for i in range(len(detections.xyxy)):
@@ -126,7 +126,7 @@ class JSONSink:
         return parsed_rows
 
     def append(
-        self, detections: Detections, custom_data: Dict[str, Any] = None
+        self, detections: Detections, custom_data: Optional[Dict[str, Any]] = None
     ) -> None:
         """
         Append detection data to the JSON file.

supervision/detection/tools/polygon_zone.py

@@ -1,6 +1,5 @@
-import warnings
 from dataclasses import replace
-from typing import Iterable, Optional, Tuple
+from typing import Iterable, Optional
 
 import cv2
 import numpy as np
@@ -9,10 +8,9 @@ import numpy.typing as npt
 from supervision import Detections
 from supervision.detection.utils import clip_boxes, polygon_to_mask
 from supervision.draw.color import Color
-from supervision.draw.utils import draw_polygon, draw_text
+from supervision.draw.utils import draw_filled_polygon, draw_polygon, draw_text
 from supervision.geometry.core import Position
 from supervision.geometry.utils import get_polygon_center
-from supervision.utils.internal import SupervisionWarnings, deprecated_parameter
 
 
 class PolygonZone:
@@ -30,28 +28,11 @@ class PolygonZone:
         mask (np.ndarray): The 2D bool mask for the polygon zone
     """
 
-    @deprecated_parameter(
-        old_parameter="triggering_position",
-        new_parameter="triggering_anchors",
-        map_function=lambda x: [x],
-        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
-        "be remove in `supervision-0.23.0`. Use '{new_parameter}' "
-        "instead.",
-    )
     def __init__(
         self,
         polygon: npt.NDArray[np.int64],
-        frame_resolution_wh: Optional[Tuple[int, int]] = None,
         triggering_anchors: Iterable[Position] = (Position.BOTTOM_CENTER,),
     ):
-        if frame_resolution_wh is not None:
-            warnings.warn(
-                "The `frame_resolution_wh` parameter is no longer required and will be "
-                "dropped in version supervision-0.24.0. The mask resolution is now "
-                "calculated automatically based on the polygon coordinates.",
-                category=SupervisionWarnings,
-            )
-
         self.polygon = polygon.astype(int)
         self.triggering_anchors = triggering_anchors
         if not list(self.triggering_anchors):
@@ -117,6 +98,7 @@ class PolygonZoneAnnotator:
             default is cv2.FONT_HERSHEY_SIMPLEX
         center (Tuple[int, int]): The center of the polygon for text placement
         display_in_zone_count (bool): Show the label of the zone or not. Default is True
+        opacity: The opacity of zone filling when drawn on the scene. Default is 0
     """
 
     def __init__(
@@ -129,6 +111,7 @@ class PolygonZoneAnnotator:
         text_thickness: int = 1,
         text_padding: int = 10,
         display_in_zone_count: bool = True,
+        opacity: float = 0,
     ):
         self.zone = zone
         self.color = color
@@ -140,6 +123,7 @@ class PolygonZoneAnnotator:
         self.font = cv2.FONT_HERSHEY_SIMPLEX
         self.center = get_polygon_center(polygon=zone.polygon)
         self.display_in_zone_count = display_in_zone_count
+        self.opacity = opacity
 
     def annotate(self, scene: np.ndarray, label: Optional[str] = None) -> np.ndarray:
         """
@@ -147,18 +131,32 @@ class PolygonZoneAnnotator:
 
         Parameters:
             scene (np.ndarray): The image on which the polygon zone will be annotated
-            label (Optional[str]): An optional label for the count of detected objects
+            label (Optional[str]): A label for the count of detected objects
                 within the polygon zone (default: None)
 
         Returns:
             np.ndarray: The image with the polygon zone and count of detected objects
         """
-        annotated_frame = draw_polygon(
-            scene=scene,
-            polygon=self.zone.polygon,
-            color=self.color,
-            thickness=self.thickness,
-        )
+        if self.opacity == 0:
+            annotated_frame = draw_polygon(
+                scene=scene,
+                polygon=self.zone.polygon,
+                color=self.color,
+                thickness=self.thickness,
+            )
+        else:
+            annotated_frame = draw_filled_polygon(
+                scene=scene.copy(),
+                polygon=self.zone.polygon,
+                color=self.color,
+                opacity=self.opacity,
+            )
+            annotated_frame = draw_polygon(
+                scene=annotated_frame,
+                polygon=self.zone.polygon,
+                color=self.color,
+                thickness=self.thickness,
+            )
 
         if self.display_in_zone_count:
             annotated_frame = draw_text(

supervision/detection/tools/smoother.py

@@ -53,7 +53,7 @@ class DetectionsSmoother:
                 annotated_frame = box_annotator.annotate(frame.copy(), detections)
                 sink.write_frame(annotated_frame)
         ```
-    """  # noqa: E501 // docs
+    """
 
     def __init__(self, length: int = 5) -> None:
         """

supervision/detection/tools/transformers.py

@@ -0,0 +1,247 @@
+import io
+from typing import Any, Dict, Optional
+
+import numpy as np
+from PIL import Image
+
+from supervision.config import CLASS_NAME_DATA_FIELD
+from supervision.detection.utils import mask_to_xyxy
+
+
+def process_transformers_detection_result(
+    detection_result: dict, id2label: Optional[Dict[int, str]]
+) -> dict:
+    """
+    Process the result of Transformers object detection functions such as
+    `post_process` (v4) and `post_process_detection` (v5).
+
+    Args:
+        detection_result (dict): Dictionary containing detection results with keys
+            'boxes', 'labels', and 'scores'.
+        id2label (Optional[Dict[int, str]]): A dictionary mapping class IDs to labels,
+            typically part of the `transformers` model configuration. If provided, the
+            resulting dictionary will include class names.
+
+    Returns:
+        dict: Processed detection result including bounding boxes, confidence scores,
+              class IDs, and data.
+    """
+    class_ids = detection_result["labels"].cpu().detach().numpy().astype(int)
+    data = append_class_names_to_data(class_ids, id2label, {})
+
+    return dict(
+        xyxy=detection_result["boxes"].cpu().detach().numpy(),
+        confidence=detection_result["scores"].cpu().detach().numpy(),
+        class_id=class_ids,
+        data=data,
+    )
+
+
+def process_transformers_v4_segmentation_result(
+    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+) -> dict:
+    """
+    Process the result of Transformers segmentation functions such as
+    `post_process_panoptic`, `post_process_segmentation`, and `post_process_instance`
+    (v4).
+
+    Args:
+        segmentation_result (dict): Dictionary containing segmentation results with keys
+            'masks', 'labels', and 'scores'.
+        id2label (Optional[Dict[int, str]]): A dictionary mapping class IDs to labels,
+            typically part of the `transformers` model configuration. If provided, the
+            resulting dictionary will include class names.
+
+    Returns:
+        dict: Processed segmentation result including bounding boxes, masks, confidence
+              scores, class IDs, and data.
+    """
+    if "png_string" in segmentation_result:
+        return process_transformers_v4_panoptic_segmentation_result(
+            segmentation_result, id2label
+        )
+    else:
+        boxes = None
+        if "boxes" in segmentation_result:
+            boxes = segmentation_result["boxes"].cpu().detach().numpy()
+        masks = segmentation_result["masks"].cpu().detach().numpy().astype(bool)
+        class_ids = segmentation_result["labels"].cpu().detach().numpy().astype(int)
+
+        return dict(
+            xyxy=boxes if boxes is not None else mask_to_xyxy(masks),
+            mask=np.squeeze(masks, axis=1) if boxes is not None else masks,
+            confidence=segmentation_result["scores"].cpu().detach().numpy(),
+            class_id=class_ids,
+            data=append_class_names_to_data(class_ids, id2label, {}),
+        )
+
+
+def process_transformers_v5_segmentation_result(
+    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+) -> dict:
+    """
+    Process the result of Transformers segmentation functions such as
+    `post_process_semantic_segmentation`, `post_process_instance_segmentation`, and
+    `post_process_panoptic_segmentation` (v5).
+
+    Args:
+        segmentation_result (Union[dict, np.ndarray]): Either a dictionary containing
+            segmentation results or an ndarray representing a segmentation map.
+        id2label (Optional[Dict[int, str]]): A dictionary mapping class IDs to labels,
+            typically part of the `transformers` model configuration. If provided, the
+            resulting dictionary will include class names.
+
+    Returns:
+        dict: Processed segmentation result including bounding boxes, masks, confidence
+              scores, class IDs, and data.
+    """
+    if segmentation_result.__class__.__name__ == "Tensor":
+        segmentation_array = segmentation_result.cpu().detach().numpy()
+        return process_transformers_v5_panoptic_segmentation_result(
+            segmentation_array, id2label
+        )
+
+    return process_transformers_v5_semantic_or_instance_segmentation_result(
+        segmentation_result, id2label
+    )
+
+
+def process_transformers_v5_semantic_or_instance_segmentation_result(
+    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+) -> dict:
+    """
+    Process the result of Transformers segmentation functions such as
+    `post_process_semantic_segmentation` and `post_process_instance_segmentation` (v5).
+
+    Args:
+        segmentation_result (dict): Dictionary containing segmentation results with keys
+            `segments_info` and `segmentation`.
+        id2label (Optional[Dict[int, str]]): A dictionary mapping class IDs to labels,
+            typically part of the `transformers` model configuration. If provided, the
+            resulting dictionary will include class names.
+
+    Returns:
+        dict: Processed segmentation result including bounding boxes, masks, confidence
+              scores, class IDs, and data.
+    """
+    segments_info = segmentation_result["segments_info"]
+    scores = np.array([segment["score"] for segment in segments_info])
+    class_ids = np.array([segment["label_id"] for segment in segments_info])
+    segmentation_array = segmentation_result["segmentation"].cpu().detach().numpy()
+    masks = np.array(
+        [segmentation_array == segment["id"] for segment in segments_info]
+    ).astype(bool)
+    data = append_class_names_to_data(class_ids, id2label, {})
+
+    return dict(
+        xyxy=mask_to_xyxy(masks),
+        mask=masks,
+        confidence=scores,
+        class_id=class_ids,
+        data=data,
+    )
+
+
+def process_transformers_v4_panoptic_segmentation_result(
+    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+) -> dict:
+    """
+    Process the result of the Transformers function `post_process_panoptic` (v4).
+
+    Args:
+        segmentation_result (dict): Dictionary containing segmentation results with keys
+            such as 'png_string' and 'segments_info'.
+        id2label (Optional[Dict[int, str]]): A dictionary mapping class IDs to labels,
+            typically part of the `transformers` model configuration. If provided, the
+            resulting dictionary will include class names.
+
+    Returns:
+        dict: Processed segmentation result including bounding boxes, masks,
+              class IDs, and data.
+    """
+    segments_info = segmentation_result["segments_info"]
+    png_string = segmentation_result["png_string"]
+    class_ids = np.array([segment["category_id"] for segment in segments_info])
+    segmentation_array = png_string_to_segmentation_array(png_string=png_string)
+    masks = np.array(
+        [segmentation_array == segment["id"] for segment in segments_info]
+    ).astype(bool)
+    data = append_class_names_to_data(class_ids, id2label, {})
+
+    return dict(
+        xyxy=mask_to_xyxy(masks),
+        mask=masks,
+        class_id=class_ids,
+        data=data,
+    )
+
+
+def process_transformers_v5_panoptic_segmentation_result(
+    segmentation_array: np.ndarray, id2label: Optional[Dict[int, str]]
+) -> dict:
+    """
+    Process the result of the Transformers function
+    `post_process_panoptic_segmentation` (v5).
+
+    Args:
+        segmentation_array (np.ndarray): Segmentation array.
+        id2label (Optional[Dict[int, str]]): A dictionary mapping class IDs to labels,
+            typically part of the `transformers` model configuration. If provided, the
+            resulting dictionary will include class names.
+
+    Returns:
+        dict: Processed segmentation result including bounding boxes, masks,
+              class IDs, and data.
+    """
+    class_ids = np.unique(segmentation_array)
+    masks = np.stack(
+        [segmentation_array == class_id for class_id in class_ids], axis=0
+    ).astype(bool)
+    data = append_class_names_to_data(class_ids, id2label, {})
+    return dict(xyxy=mask_to_xyxy(masks), mask=masks, class_id=class_ids, data=data)
+
+
+def png_string_to_segmentation_array(png_string: bytes) -> np.ndarray:
+    """
+    Convert a PNG byte string to a label mask array.
+
+    Args:
+        png_string (bytes): A byte string representing the PNG image.
+
+    Returns:
+        np.ndarray: A label mask array with shape (H, W), where H and W
+        are the height and width of the image. Each unique value in the array
+        represents a different object or category.
+    """
+    image = Image.open(io.BytesIO(png_string))
+    mask = np.array(image, dtype=np.uint8)
+    return mask[:, :, 0]
+
+
+def append_class_names_to_data(
+    class_ids: np.ndarray,
+    id2label: Optional[Dict[int, str]],
+    data: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """
+    Helper function to create or append to a data dictionary with class names if
+    available.
+
+    Args:
+        class_ids (np.ndarray): Array of class IDs.
+        id2label (Optional[Dict[int, str]]): A dictionary mapping class IDs to labels,
+            typically part of the `transformers` model configuration. If provided, the
+            resulting dictionary will include class names.
+        data (Optional[Dict[str, Any]]): An existing data dictionary to append to.
+
+    Returns:
+        Dict[str, Any]: Dictionary containing class names if id2label is provided.
+    """
+    if data is None:
+        data = {}
+
+    if id2label is not None:
+        class_names = np.array([id2label[class_id] for class_id in class_ids])
+        data[CLASS_NAME_DATA_FIELD] = class_names
+
+    return data

supervision/detection/utils.py

@@ -106,7 +106,7 @@ def mask_iou_batch(
     Args:
         masks_true (np.ndarray): 3D `np.ndarray` representing ground-truth masks.
         masks_detection (np.ndarray): 3D `np.ndarray` representing detection masks.
-        memory_limit (int, optional): memory limit in MB, default is 1024 * 5 MB (5GB).
+        memory_limit (int): memory limit in MB, default is 1024 * 5 MB (5GB).
 
     Returns:
         np.ndarray: Pairwise IoU of masks from `masks_true` and `masks_detection`.
@@ -140,6 +140,45 @@ def mask_iou_batch(
     return np.vstack(ious)
 
 
+def oriented_box_iou_batch(
+    boxes_true: np.ndarray, boxes_detection: np.ndarray
+) -> np.ndarray:
+    """
+    Compute Intersection over Union (IoU) of two sets of oriented bounding boxes -
+    `boxes_true` and `boxes_detection`. Both sets of boxes are expected to be in
+    `((x1, y1), (x2, y2), (x3, y3), (x4, y4))` format.
+
+    Args:
+        boxes_true (np.ndarray): a `np.ndarray` representing ground-truth boxes.
+            `shape = (N, 4, 2)` where `N` is number of true objects.
+        boxes_detection (np.ndarray): a `np.ndarray` representing detection boxes.
+            `shape = (M, 4, 2)` where `M` is number of detected objects.
+
+    Returns:
+        np.ndarray: Pairwise IoU of boxes from `boxes_true` and `boxes_detection`.
+            `shape = (N, M)` where `N` is number of true objects and
+            `M` is number of detected objects.
+    """
+
+    boxes_true = boxes_true.reshape(-1, 4, 2)
+    boxes_detection = boxes_detection.reshape(-1, 4, 2)
+
+    max_height = max(boxes_true[:, :, 0].max(), boxes_detection[:, :, 0].max()) + 1
+    # adding 1 because we are 0-indexed
+    max_width = max(boxes_true[:, :, 1].max(), boxes_detection[:, :, 1].max()) + 1
+
+    mask_true = np.zeros((boxes_true.shape[0], max_height, max_width))
+    for i, box_true in enumerate(boxes_true):
+        mask_true[i] = polygon_to_mask(box_true, (max_width, max_height))
+
+    mask_detection = np.zeros((boxes_detection.shape[0], max_height, max_width))
+    for i, box_detection in enumerate(boxes_detection):
+        mask_detection[i] = polygon_to_mask(box_detection, (max_width, max_height))
+
+    ious = mask_iou_batch(mask_true, mask_detection)
+    return ious
+
+
 def clip_boxes(xyxy: np.ndarray, resolution_wh: Tuple[int, int]) -> np.ndarray:
     """
     Clips bounding boxes coordinates to fit within the frame resolution.
@@ -147,7 +186,7 @@ def clip_boxes(xyxy: np.ndarray, resolution_wh: Tuple[int, int]) -> np.ndarray:
     Args:
         xyxy (np.ndarray): A numpy array of shape `(N, 4)` where each
             row corresponds to a bounding box in
-        the format `(x_min, y_min, x_max, y_max)`.
+            the format `(x_min, y_min, x_max, y_max)`.
         resolution_wh (Tuple[int, int]): A tuple of the form `(width, height)`
             representing the resolution of the frame.
 
@@ -596,6 +635,61 @@ def move_boxes(
     return xyxy + np.hstack([offset, offset])
 
 
+def move_oriented_boxes(
+    xyxyxyxy: npt.NDArray[np.float64], offset: npt.NDArray[np.int32]
+) -> npt.NDArray[np.float64]:
+    """
+    Parameters:
+    xyxyxyxy (npt.NDArray[np.float64]): An array of shape `(n, 4, 2)` containing the
+    oriented bounding boxes coordinates in format
+    `[[x1, y1], [x2, y2], [x3, y3], [x3, y3]]`
+    offset (np.array): An array of shape `(2,)` containing offset values in format
+        is `[dx, dy]`.
+
+    Returns:
+    npt.NDArray[np.float64]: Repositioned bounding boxes.
+
+    Examples:
+    ```python
+    import numpy as np
+    import supervision as sv
+
+    xyxyxyxy = np.array([
+        [
+            [20, 10],
+            [10, 20],
+            [20, 30],
+            [30, 20]
+        ],
+        [
+            [30 ,30],
+            [20, 40],
+            [30, 50],
+            [40, 40]
+        ]
+    ])
+    offset = np.array([5, 5])
+
+    sv.move_oriented_boxes(xyxy=xyxy, offset=offset)
+    # array([
+    #     [
+    #         [25, 15],
+    #         [15, 25],
+    #         [25, 35],
+    #         [35, 25]
+    #     ],
+    #     [
+    #         [35, 35],
+    #         [25, 45],
+    #         [35, 55],
+    #         [45, 45]
+    #     ]
+    # ])
+    ```
+    """
+    return xyxyxyxy + offset
+
+
 def move_masks(
     masks: npt.NDArray[np.bool_],
     offset: npt.NDArray[np.int32],

supervision/draw/color.py

@@ -255,6 +255,17 @@ class Color:
     def ROBOFLOW(cls) -> Color:
         return Color.from_hex("#A351FB")
 
+    def __hash__(self):
+        return hash((self.r, self.g, self.b))
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, Color)
+            and self.r == other.r
+            and self.g == other.g
+            and self.b == other.b
+        )
+
 
 @dataclass
 class ColorPalette:
@@ -352,11 +363,15 @@ class ColorPalette:
         supervision-annotator-examples/visualized_color_palette.png)
         """  # noqa: E501 // docs
         mpl_palette = plt.get_cmap(palette_name, color_count)
-        colors = [
-            Color(int(r * 255), int(g * 255), int(b * 255))
-            for r, g, b, _ in mpl_palette.colors
-        ]
-        return cls(colors)
+
+        if hasattr(mpl_palette, "colors"):
+            colors = mpl_palette.colors
+        else:
+            colors = [mpl_palette(i / (color_count - 1)) for i in range(color_count)]
+
+        return cls(
+            [Color(int(r * 255), int(g * 255), int(b * 255)) for r, g, b, _ in colors]
+        )
 
     def by_idx(self, idx: int) -> Color:
         """
@@ -382,6 +397,15 @@ class ColorPalette:
         idx = idx % len(self.colors)
         return self.colors[idx]
 
+    def __len__(self) -> int:
+        """
+        Returns the number of colors in the palette.
+
+        Returns:
+            int: The number of colors.
+        """
+        return len(self.colors)
+
 
 def unify_to_bgr(color: Union[Tuple[int, int, int], Color]) -> Tuple[int, int, int]:
     """

supervision/draw/utils.py

@@ -59,7 +59,9 @@ def draw_rectangle(
     return scene
 
 
-def draw_filled_rectangle(scene: np.ndarray, rect: Rect, color: Color) -> np.ndarray:
+def draw_filled_rectangle(
+    scene: np.ndarray, rect: Rect, color: Color, opacity: float = 1
+) -> np.ndarray:
     """
     Draws a filled rectangle on an image.
 
@@ -67,17 +69,32 @@ def draw_filled_rectangle(scene: np.ndarray, rect: Rect, color: Color) -> np.nda
         scene (np.ndarray): The scene on which the rectangle will be drawn
         rect (Rect): The rectangle to be drawn
         color (Color): The color of the rectangle
+        opacity (float): The opacity of rectangle when drawn on the scene.
 
     Returns:
         np.ndarray: The scene with the rectangle drawn on it
     """
-    cv2.rectangle(
-        scene,
-        rect.top_left.as_xy_int_tuple(),
-        rect.bottom_right.as_xy_int_tuple(),
-        color.as_bgr(),
-        -1,
-    )
+    if opacity == 1:
+        cv2.rectangle(
+            scene,
+            rect.top_left.as_xy_int_tuple(),
+            rect.bottom_right.as_xy_int_tuple(),
+            color.as_bgr(),
+            -1,
+        )
+    else:
+        scene_with_annotations = scene.copy()
+        cv2.rectangle(
+            scene_with_annotations,
+            rect.top_left.as_xy_int_tuple(),
+            rect.bottom_right.as_xy_int_tuple(),
+            color.as_bgr(),
+            -1,
+        )
+        cv2.addWeighted(
+            scene_with_annotations, opacity, scene, 1 - opacity, gamma=0, dst=scene
+        )
+
     return scene
 
 
@@ -142,7 +159,7 @@ def draw_polygon(
         scene (np.ndarray): The scene to draw the polygon on.
         polygon (np.ndarray): The polygon to be drawn, given as a list of vertices.
         color (Color): The color of the polygon.
-        thickness (int, optional): The thickness of the polygon lines, by default 2.
+        thickness (int): The thickness of the polygon lines, by default 2.
 
     Returns:
         np.ndarray: The scene with the polygon drawn on it.
@@ -153,6 +170,32 @@ def draw_polygon(
     return scene
 
 
+def draw_filled_polygon(
+    scene: np.ndarray, polygon: np.ndarray, color: Color, opacity: float = 1
+) -> np.ndarray:
+    """Draw a filled polygon on a scene.
+
+    Parameters:
+        scene (np.ndarray): The scene to draw the polygon on.
+        polygon (np.ndarray): The polygon to be drawn, given as a list of vertices.
+        color (Color): The color of the polygon.
+        opacity (float): The opacity of polygon when drawn on the scene.
+
+    Returns:
+        np.ndarray: The scene with the polygon drawn on it.
+    """
+    if opacity == 1:
+        cv2.fillPoly(scene, [polygon], color=color.as_bgr())
+    else:
+        scene_with_annotations = scene.copy()
+        cv2.fillPoly(scene_with_annotations, [polygon], color=color.as_bgr())
+        cv2.addWeighted(
+            scene_with_annotations, opacity, scene, 1 - opacity, gamma=0, dst=scene
+        )
+
+    return scene
+
+
 def draw_text(
     scene: np.ndarray,
     text: str,
@@ -172,14 +215,14 @@ def draw_text(
         text (str): The text to be drawn.
         text_anchor (Point): The anchor point for the text, represented as a
             Point object with x and y attributes.
-        text_color (Color, optional): The color of the text. Defaults to black.
-        text_scale (float, optional): The scale of the text. Defaults to 0.5.
-        text_thickness (int, optional): The thickness of the text. Defaults to 1.
-        text_padding (int, optional): The amount of padding to add around the text
+        text_color (Color): The color of the text. Defaults to black.
+        text_scale (float): The scale of the text. Defaults to 0.5.
+        text_thickness (int): The thickness of the text. Defaults to 1.
+        text_padding (int): The amount of padding to add around the text
             when drawing a rectangle in the background. Defaults to 10.
-        text_font (int, optional): The font to use for the text.
+        text_font (int): The font to use for the text.
             Defaults to cv2.FONT_HERSHEY_SIMPLEX.
-        background_color (Color, optional): The color of the background rectangle,
+        background_color (Optional[Color]): The color of the background rectangle,
             if one is to be drawn. Defaults to None.
 
     Returns:

supervision/keypoint/annotators.py

@@ -34,8 +34,8 @@ class VertexAnnotator(BaseKeyPointAnnotator):
     ) -> None:
         """
         Args:
-            color (Color, optional): The color to use for annotating key points.
-            radius (int, optional): The radius of the circles used to represent the key
+            color (Color): The color to use for annotating key points.
+            radius (int): The radius of the circles used to represent the key
                 points.
         """
         self.color = color
@@ -78,6 +78,7 @@ class VertexAnnotator(BaseKeyPointAnnotator):
         ![vertex-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/vertex-annotator-example.png)
         """
+        assert isinstance(scene, np.ndarray)
         if len(key_points) == 0:
             return scene
 
@@ -108,8 +109,8 @@ class EdgeAnnotator(BaseKeyPointAnnotator):
     ) -> None:
         """
         Args:
-            color (Color, optional): The color to use for the edges.
-            thickness (int, optional): The thickness of the edges.
+            color (Color): The color to use for the edges.
+            thickness (int): The thickness of the edges.
             edges (Optional[List[Tuple[int, int]]]): The edges to draw.
                 If set to `None`, will attempt to select automatically.
         """
@@ -155,6 +156,7 @@ class EdgeAnnotator(BaseKeyPointAnnotator):
         ![edge-annotator-example](https://media.roboflow.com/
         supervision-annotator-examples/edge-annotator-example.png)
         """
+        assert isinstance(scene, np.ndarray)
         if len(key_points) == 0:
             return scene
 
@@ -194,7 +196,7 @@ class VertexLabelAnnotator:
     def __init__(
         self,
         color: Union[Color, List[Color]] = Color.ROBOFLOW,
-        text_color: Color = Color.WHITE,
+        text_color: Union[Color, List[Color]] = Color.WHITE,
         text_scale: float = 0.5,
         text_thickness: int = 1,
         text_padding: int = 10,
@@ -202,25 +204,30 @@ class VertexLabelAnnotator:
     ):
         """
         Args:
-            color (Union[Color, List[Color]], optional): The color to use for each
+            color (Union[Color, List[Color]]): The color to use for each
                 keypoint label. If a list is provided, the colors will be used in order
                 for each keypoint.
-            text_color (Color, optional): The color to use for the labels.
-            text_scale (float, optional): The scale of the text.
-            text_thickness (int, optional): The thickness of the text.
-            text_padding (int, optional): The padding around the text.
-            border_radius (int, optional): The radius of the rounded corners of the
+            text_color (Union[Color, List[Color]]): The color to use
+                for the labels. If a list is provided, the colors will be used in order
+                for each keypoint.
+            text_scale (float): The scale of the text.
+            text_thickness (int): The thickness of the text.
+            text_padding (int): The padding around the text.
+            border_radius (int): The radius of the rounded corners of the
                 boxes. Set to a high value to produce circles.
         """
         self.border_radius: int = border_radius
         self.color: Union[Color, List[Color]] = color
-        self.text_color: Color = text_color
+        self.text_color: Union[Color, List[Color]] = text_color
         self.text_scale: float = text_scale
         self.text_thickness: int = text_thickness
         self.text_padding: int = text_padding
 
     def annotate(
-        self, scene: ImageType, key_points: KeyPoints, labels: List[str] = None
+        self,
+        scene: ImageType,
+        key_points: KeyPoints,
+        labels: Optional[List[str]] = None,
     ) -> ImageType:
         """
         A class that draws labels of skeleton vertices on images. It uses specified key
@@ -232,7 +239,7 @@ class VertexLabelAnnotator:
                 `PIL.Image.Image`.
             key_points (KeyPoints): A collection of key points where each key point
                 consists of x and y coordinates.
-            labels (List[str], optional): A list of labels to be displayed on the
+            labels (Optional[List[str]]): A list of labels to be displayed on the
                 annotated image. If not provided, keypoint indices will be used.
 
         Returns:
@@ -303,6 +310,7 @@ class VertexLabelAnnotator:
         ![vertex-label-annotator-custom-example](https://media.roboflow.com/
         supervision-annotator-examples/vertex-label-annotator-custom-example.png)
         """
+        assert isinstance(scene, np.ndarray)
         font = cv2.FONT_HERSHEY_SIMPLEX
 
         skeletons_count, points_count, _ = key_points.xy.shape
@@ -321,12 +329,19 @@ class VertexLabelAnnotator:
             skeletons_count=skeletons_count,
         )
 
+        text_colors = self.preprocess_and_validate_colors(
+            colors=self.text_color,
+            points_count=points_count,
+            skeletons_count=skeletons_count,
+        )
+
         labels = self.preprocess_and_validate_labels(
             labels=labels, points_count=points_count, skeletons_count=skeletons_count
         )
 
         anchors = anchors[mask]
         colors = colors[mask]
+        text_colors = text_colors[mask]
         labels = labels[mask]
 
         xyxy = np.array(
@@ -344,7 +359,9 @@ class VertexLabelAnnotator:
 
         xyxy_padded = pad_boxes(xyxy=xyxy, px=self.text_padding)
 
-        for text, color, box, box_padded in zip(labels, colors, xyxy, xyxy_padded):
+        for text, color, text_color, box, box_padded in zip(
+            labels, colors, text_colors, xyxy, xyxy_padded
+        ):
             draw_rounded_rectangle(
                 scene=scene,
                 rect=Rect.from_xyxy(box_padded),
@@ -354,10 +371,10 @@ class VertexLabelAnnotator:
             cv2.putText(
                 img=scene,
                 text=text,
-                org=(box[0], box[1] + self.text_padding),
+                org=(box[0], box[3]),
                 fontFace=font,
                 fontScale=self.text_scale,
-                color=self.text_color.as_rgb(),
+                color=text_color.as_bgr(),
                 thickness=self.text_thickness,
                 lineType=cv2.LINE_AA,
             )
@@ -389,7 +406,7 @@ class VertexLabelAnnotator:
     @staticmethod
     def preprocess_and_validate_labels(
         labels: Optional[List[str]], points_count: int, skeletons_count: int
-    ) -> np.array:
+    ) -> np.ndarray:
         if labels and len(labels) != points_count:
             raise ValueError(
                 f"Number of labels ({len(labels)}) must match number of key points "
@@ -405,7 +422,7 @@ class VertexLabelAnnotator:
         colors: Optional[Union[Color, List[Color]]],
         points_count: int,
         skeletons_count: int,
-    ) -> np.array:
+    ) -> np.ndarray:
         if isinstance(colors, list) and len(colors) != points_count:
             raise ValueError(
                 f"Number of colors ({len(colors)}) must match number of key points "

supervision/keypoint/core.py

@@ -18,11 +18,11 @@ class KeyPoints:
     The `sv.KeyPoints` class in the Supervision library standardizes results from
     various keypoint detection and pose estimation models into a consistent format. This
     class simplifies data manipulation and filtering, providing a uniform API for
-    integration with Supervision [keypoints annotators](/keypoint/annotators).
+    integration with Supervision [keypoints annotators](/latest/keypoint/annotators).
 
     === "Ultralytics"
 
-        Use [`sv.KeyPoints.from_ultralytics`](/keypoint/core/#supervision.keypoint.core.KeyPoints.from_ultralytics)
+        Use [`sv.KeyPoints.from_ultralytics`](/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_ultralytics)
         method, which accepts [YOLOv8](https://github.com/ultralytics/ultralytics)
         pose result.
 
@@ -40,7 +40,7 @@ class KeyPoints:
 
     === "Inference"
 
-        Use [`sv.KeyPoints.from_inference`](/keypoint/core/#supervision.keypoint.core.KeyPoints.from_inference)
+        Use [`sv.KeyPoints.from_inference`](/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_inference)
         method, which accepts [Inference](https://inference.roboflow.com/) pose result.
 
         ```python
@@ -57,7 +57,7 @@ class KeyPoints:
 
     === "MediaPipe"
 
-        Use [`sv.KeyPoints.from_mediapipe`](/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe)
+        Use [`sv.KeyPoints.from_mediapipe`](/latest/keypoint/core/#supervision.keypoint.core.KeyPoints.from_mediapipe)
         method, which accepts [MediaPipe](https://github.com/google-ai-edge/mediapipe)
         pose result.
 
@@ -88,15 +88,17 @@ class KeyPoints:
         ```
 
     Attributes:
-        xy (np.ndarray): An array of shape `(n, 2)` containing
-            the bounding boxes coordinates in format `[x1, y1]`
+        xy (np.ndarray): An array of shape `(n, m, 2)` containing
+            `n` detected objects, each composed of `m` equally-sized
+            sets of keypoints, where each point is `[x, y]`.
         confidence (Optional[np.ndarray]): An array of shape
-            `(n,)` containing the confidence scores of the keypoint keypoints.
+            `(n, m)` containing the confidence scores of each keypoint.
         class_id (Optional[np.ndarray]): An array of shape
-            `(n,)` containing the class ids of the keypoint keypoints.
+            `(n,)` containing the class ids of the detected objects.
         data (Dict[str, Union[np.ndarray, List]]): A dictionary containing additional
             data where each key is a string representing the data type, and the value
-            is either a NumPy array or a list of corresponding data.
+            is either a NumPy array or a list of corresponding data of length `n`
+            (one entry per detected object).
     """  # noqa: E501 // docs
 
     xy: npt.NDArray[np.float32]
@@ -132,7 +134,7 @@ class KeyPoints:
     ]:
         """
         Iterates over the Keypoint object and yield a tuple of
-        `(xy, confidence, class_id, data)` for each keypoint detection.
+        `(xy, confidence, class_id, data)` for each object detection.
         """
         for i in range(len(self.xy)):
             yield (
@@ -427,7 +429,7 @@ class KeyPoints:
             results = model.predict(image, conf=0.1)
             key_points = sv.KeyPoints.from_yolo_nas(results)
             ```
-        """  # noqa: E501 // docs
+        """
         if len(yolo_nas_results.prediction.poses) == 0:
             return cls.empty()
 
@@ -457,13 +459,13 @@ class KeyPoints:
         )
 
     @classmethod
-    def from_detectron2(cls, detectron2_results) -> KeyPoints:
+    def from_detectron2(cls, detectron2_results: Any) -> KeyPoints:
         """
         Create a `sv.KeyPoints` object from the
         [Detectron2](https://github.com/facebookresearch/detectron2) inference result.
 
         Args:
-            detectron2_results: The output of a
+            detectron2_results (Any): The output of a
                 Detectron2 model containing instances with prediction data.
 
         Returns:

supervision/keypoint/skeletons.py

@@ -1,11 +1,11 @@
 from enum import Enum
-from typing import Dict, List, Tuple
+from typing import Dict, Tuple
 
-Edges = List[Tuple[int, int]]
+Edges = Tuple[Tuple[int, int], ...]
 
 
 class Skeleton(Enum):
-    COCO = [
+    COCO: Edges = (
         (1, 2),
         (1, 3),
         (2, 3),
@@ -23,9 +23,9 @@ class Skeleton(Enum):
         (15, 13),
         (16, 14),
         (17, 15),
-    ]
+    )
 
-    GHUM = [
+    GHUM: Edges = (
         (1, 2),
         (1, 5),
         (2, 3),
@@ -61,9 +61,9 @@ class Skeleton(Enum):
         (29, 33),
         (30, 32),
         (31, 33),
-    ]
+    )
 
-    FACEMESH_TESSELATION_NO_IRIS = [
+    FACEMESH_TESSELATION_NO_IRIS: Edges = (
         (128, 35),
         (35, 140),
         (140, 128),
@@ -2620,9 +2620,9 @@ class Skeleton(Enum):
         (340, 449),
         (449, 256),
         (256, 340),
-    ]
+    )
 
-    FACEMESH_TESSELATION = [
+    FACEMESH_TESSELATION: Edges = (
         (474, 474),
         (475, 476),
         (476, 477),
@@ -2633,7 +2633,8 @@ class Skeleton(Enum):
         (471, 472),
         (472, 473),
         (473, 470),
-    ] + FACEMESH_TESSELATION_NO_IRIS
+        *FACEMESH_TESSELATION_NO_IRIS,
+    )
 
 
 SKELETONS_BY_EDGE_COUNT: Dict[int, Edges] = {}

supervision/metrics/__init__.py

@@ -0,0 +1,16 @@
+from supervision.metrics.core import (
+    CLASS_ID_NONE,
+    AveragingMethod,
+    Metric,
+    MetricTarget,
+)
+from supervision.metrics.f1_score import F1Score, F1ScoreResult
+from supervision.metrics.mean_average_precision import (
+    MeanAveragePrecision,
+    MeanAveragePrecisionResult,
+)
+from supervision.metrics.utils.object_size import (
+    ObjectSizeCategory,
+    get_detection_size_category,
+    get_object_size_category,
+)

supervision/metrics/core.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any
+
+CLASS_ID_NONE = -1
+"""Used by metrics module as class ID, when none is present"""
+
+
+class Metric(ABC):
+    """
+    The base class for all supervision metrics.
+    """
+
+    @abstractmethod
+    def update(self, *args, **kwargs) -> "Metric":
+        """
+        Add data to the metric, without computing the result.
+        Return the metric itself to allow method chaining.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def reset(self) -> None:
+        """
+        Reset internal metric state.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def compute(self, *args, **kwargs) -> Any:
+        """
+        Compute the metric from the internal state and return the result.
+        """
+        raise NotImplementedError
+
+
+class MetricTarget(Enum):
+    """
+    Specifies what type of detection is used to compute the metric.
+
+    * BOXES: xyxy bounding boxes
+    * MASKS: Binary masks
+    * ORIENTED_BOUNDING_BOXES: Oriented bounding boxes (OBB)
+    """
+
+    BOXES = "boxes"
+    MASKS = "masks"
+    ORIENTED_BOUNDING_BOXES = "obb"
+
+
+class AveragingMethod(Enum):
+    """
+    Defines different ways of averaging the metric results.
+
+    Suppose, before returning the final result, a metric is computed for each class.
+    How do you combine those to get the final number?
+
+    * MACRO: Calculate the metric for each class and average the results. The simplest
+        averaging method, but it does not take class imbalance into account.
+    * MICRO: Calculate the metric globally by counting the total true positives, false
+        positives, and false negatives. Micro averaging is useful when you want to give
+        more importance to classes with more samples. It's also more appropriate if you
+        have an imbalance in the number of instances per class.
+    * WEIGHTED: Calculate the metric for each class and average the results, weighted by
+        the number of true instances of each class. Use weighted averaging if you want
+        to take class imbalance into account.
+    """
+
+    MACRO = "macro"
+    MICRO = "micro"
+    WEIGHTED = "weighted"

supervision/metrics/detection.py

@@ -391,11 +391,10 @@ class ConfusionMatrix:
             ```
         """
         predictions, targets = [], []
-        for img_name, img in dataset.images.items():
-            predictions_batch = callback(img)
+        for _, image, annotation in dataset:
+            predictions_batch = callback(image)
             predictions.append(predictions_batch)
-            targets_batch = dataset.annotations[img_name]
-            targets.append(targets_batch)
+            targets.append(annotation)
         return cls.from_detections(
             predictions=predictions,
             targets=targets,
@@ -441,8 +440,8 @@ class ConfusionMatrix:
         class_names = classes if classes is not None else self.classes
         use_labels_for_ticks = class_names is not None and (0 < len(class_names) < 99)
         if use_labels_for_ticks:
-            x_tick_labels = class_names + ["FN"]
-            y_tick_labels = class_names + ["FP"]
+            x_tick_labels = [*class_names, "FN"]
+            y_tick_labels = [*class_names, "FP"]
             num_ticks = len(x_tick_labels)
         else:
             x_tick_labels = None
@@ -604,11 +603,10 @@ class MeanAveragePrecision:
             ```
         """
         predictions, targets = [], []
-        for img_name, img in dataset.images.items():
-            predictions_batch = callback(img)
+        for _, image, annotation in dataset:
+            predictions_batch = callback(image)
             predictions.append(predictions_batch)
-            targets_batch = dataset.annotations[img_name]
-            targets.append(targets_batch)
+            targets.append(annotation)
         return cls.from_detections(
             predictions=predictions,
             targets=targets,
@@ -666,12 +664,12 @@ class MeanAveragePrecision:
                 np.array([[1.0, 1.0, 2.0, 2.0, 2, 0.8]])
             ]
 
-            mean_average_precison = sv.MeanAveragePrecision.from_tensors(
+            mean_average_precision = sv.MeanAveragePrecision.from_tensors(
                 predictions=predictions,
                 targets=targets,
             )
 
-            print(mean_average_precison.map50_95)
+            print(mean_average_precision.map50_95)
             # 0.6649
             ```
         """
@@ -808,7 +806,7 @@ class MeanAveragePrecision:
             prediction_confidence (np.ndarray): Objectness value from 0-1.
             prediction_class_ids (np.ndarray): Predicted object classes.
             true_class_ids (np.ndarray): True object classes.
-            eps (float, optional): Small value to prevent division by zero.
+            eps (float): Small value to prevent division by zero.
 
         Returns:
             np.ndarray: Average precision for different IoU levels.

supervision/metrics/f1_score.py

@@ -0,0 +1,545 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List, Optional, Tuple, Union
+
+import numpy as np
+from matplotlib import pyplot as plt
+
+from supervision.config import ORIENTED_BOX_COORDINATES
+from supervision.detection.core import Detections
+from supervision.detection.utils import box_iou_batch, mask_iou_batch
+from supervision.draw.color import LEGACY_COLOR_PALETTE
+from supervision.metrics.core import AveragingMethod, Metric, MetricTarget
+from supervision.metrics.utils.object_size import (
+    ObjectSizeCategory,
+    get_detection_size_category,
+)
+from supervision.metrics.utils.utils import ensure_pandas_installed
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class F1Score(Metric):
+    def __init__(
+        self,
+        metric_target: MetricTarget = MetricTarget.BOXES,
+        averaging_method: AveragingMethod = AveragingMethod.WEIGHTED,
+    ):
+        self._metric_target = metric_target
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            raise NotImplementedError(
+                "F1 score is not implemented for oriented bounding boxes."
+            )
+
+        self._metric_target = metric_target
+        self.averaging_method = averaging_method
+        self._predictions_list: List[Detections] = []
+        self._targets_list: List[Detections] = []
+
+    def reset(self) -> None:
+        self._predictions_list = []
+        self._targets_list = []
+
+    def update(
+        self,
+        predictions: Union[Detections, List[Detections]],
+        targets: Union[Detections, List[Detections]],
+    ) -> F1Score:
+        if not isinstance(predictions, list):
+            predictions = [predictions]
+        if not isinstance(targets, list):
+            targets = [targets]
+
+        if len(predictions) != len(targets):
+            raise ValueError(
+                f"The number of predictions ({len(predictions)}) and"
+                f" targets ({len(targets)}) during the update must be the same."
+            )
+
+        self._predictions_list.extend(predictions)
+        self._targets_list.extend(targets)
+
+        return self
+
+    def compute(self) -> F1ScoreResult:
+        result = self._compute(self._predictions_list, self._targets_list)
+
+        small_predictions, small_targets = self._filter_predictions_and_targets_by_size(
+            self._predictions_list, self._targets_list, ObjectSizeCategory.SMALL
+        )
+        result.small_objects = self._compute(small_predictions, small_targets)
+
+        medium_predictions, medium_targets = (
+            self._filter_predictions_and_targets_by_size(
+                self._predictions_list, self._targets_list, ObjectSizeCategory.MEDIUM
+            )
+        )
+        result.medium_objects = self._compute(medium_predictions, medium_targets)
+
+        large_predictions, large_targets = self._filter_predictions_and_targets_by_size(
+            self._predictions_list, self._targets_list, ObjectSizeCategory.LARGE
+        )
+        result.large_objects = self._compute(large_predictions, large_targets)
+
+        return result
+
+    def _compute(
+        self, predictions_list: List[Detections], targets_list: List[Detections]
+    ) -> F1ScoreResult:
+        iou_thresholds = np.linspace(0.5, 0.95, 10)
+        stats = []
+
+        for predictions, targets in zip(predictions_list, targets_list):
+            prediction_contents = self._detections_content(predictions)
+            target_contents = self._detections_content(targets)
+
+            if len(targets) > 0:
+                if len(predictions) == 0:
+                    stats.append(
+                        (
+                            np.zeros((0, iou_thresholds.size), dtype=bool),
+                            np.zeros((0,), dtype=np.float32),
+                            np.zeros((0,), dtype=int),
+                            targets.class_id,
+                        )
+                    )
+
+                else:
+                    if self._metric_target == MetricTarget.BOXES:
+                        iou = box_iou_batch(target_contents, prediction_contents)
+                    elif self._metric_target == MetricTarget.MASKS:
+                        iou = mask_iou_batch(target_contents, prediction_contents)
+                    else:
+                        raise NotImplementedError(
+                            "Unsupported metric target for IoU calculation"
+                        )
+
+                    matches = self._match_detection_batch(
+                        predictions.class_id, targets.class_id, iou, iou_thresholds
+                    )
+                    stats.append(
+                        (
+                            matches,
+                            predictions.confidence,
+                            predictions.class_id,
+                            targets.class_id,
+                        )
+                    )
+
+        if not stats:
+            return F1ScoreResult(
+                metric_target=self._metric_target,
+                averaging_method=self.averaging_method,
+                f1_scores=np.zeros(iou_thresholds.shape[0]),
+                f1_per_class=np.zeros((0, iou_thresholds.shape[0])),
+                iou_thresholds=iou_thresholds,
+                matched_classes=np.array([], dtype=int),
+                small_objects=None,
+                medium_objects=None,
+                large_objects=None,
+            )
+
+        concatenated_stats = [np.concatenate(items, 0) for items in zip(*stats)]
+        f1_scores, f1_per_class, unique_classes = self._compute_f1_for_classes(
+            *concatenated_stats
+        )
+
+        return F1ScoreResult(
+            metric_target=self._metric_target,
+            averaging_method=self.averaging_method,
+            f1_scores=f1_scores,
+            f1_per_class=f1_per_class,
+            iou_thresholds=iou_thresholds,
+            matched_classes=unique_classes,
+            small_objects=None,
+            medium_objects=None,
+            large_objects=None,
+        )
+
+    def _compute_f1_for_classes(
+        self,
+        matches: np.ndarray,
+        prediction_confidence: np.ndarray,
+        prediction_class_ids: np.ndarray,
+        true_class_ids: np.ndarray,
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        sorted_indices = np.argsort(-prediction_confidence)
+        matches = matches[sorted_indices]
+        prediction_class_ids = prediction_class_ids[sorted_indices]
+        unique_classes, class_counts = np.unique(true_class_ids, return_counts=True)
+
+        # Shape: PxTh,P,C,C -> CxThx3
+        confusion_matrix = self._compute_confusion_matrix(
+            matches, prediction_class_ids, unique_classes, class_counts
+        )
+
+        # Shape: CxThx3 -> CxTh
+        f1_per_class = self._compute_f1(confusion_matrix)
+
+        # Shape: CxTh -> Th
+        if self.averaging_method == AveragingMethod.MACRO:
+            f1_scores = np.mean(f1_per_class, axis=0)
+        elif self.averaging_method == AveragingMethod.MICRO:
+            confusion_matrix_merged = confusion_matrix.sum(0)
+            f1_scores = self._compute_f1(confusion_matrix_merged)
+        elif self.averaging_method == AveragingMethod.WEIGHTED:
+            class_counts = class_counts.astype(np.float32)
+            f1_scores = np.average(f1_per_class, axis=0, weights=class_counts)
+
+        return f1_scores, f1_per_class, unique_classes
+
+    @staticmethod
+    def _match_detection_batch(
+        predictions_classes: np.ndarray,
+        target_classes: np.ndarray,
+        iou: np.ndarray,
+        iou_thresholds: np.ndarray,
+    ) -> np.ndarray:
+        num_predictions, num_iou_levels = (
+            predictions_classes.shape[0],
+            iou_thresholds.shape[0],
+        )
+        correct = np.zeros((num_predictions, num_iou_levels), dtype=bool)
+        correct_class = target_classes[:, None] == predictions_classes
+
+        for i, iou_level in enumerate(iou_thresholds):
+            matched_indices = np.where((iou >= iou_level) & correct_class)
+
+            if matched_indices[0].shape[0]:
+                combined_indices = np.stack(matched_indices, axis=1)
+                iou_values = iou[matched_indices][:, None]
+                matches = np.hstack([combined_indices, iou_values])
+
+                if matched_indices[0].shape[0] > 1:
+                    matches = matches[matches[:, 2].argsort()[::-1]]
+                    matches = matches[np.unique(matches[:, 1], return_index=True)[1]]
+                    matches = matches[np.unique(matches[:, 0], return_index=True)[1]]
+
+                correct[matches[:, 1].astype(int), i] = True
+
+        return correct
+
+    @staticmethod
+    def _compute_confusion_matrix(
+        sorted_matches: np.ndarray,
+        sorted_prediction_class_ids: np.ndarray,
+        unique_classes: np.ndarray,
+        class_counts: np.ndarray,
+    ) -> np.ndarray:
+        """
+        Compute the confusion matrix for each class and IoU threshold.
+
+        Assumes the matches and prediction_class_ids are sorted by confidence
+        in descending order.
+
+        Arguments:
+            sorted_matches: np.ndarray, bool, shape (P, Th), that is True
+                if the prediction is a true positive at the given IoU threshold.
+            sorted_prediction_class_ids: np.ndarray, int, shape (P,), containing
+                the class id for each prediction.
+            unique_classes: np.ndarray, int, shape (C,), containing the unique
+                class ids.
+            class_counts: np.ndarray, int, shape (C,), containing the number
+                of true instances for each class.
+
+        Returns:
+            np.ndarray, shape (C, Th, 3), containing the true positives, false
+                positives, and false negatives for each class and IoU threshold.
+        """
+
+        num_thresholds = sorted_matches.shape[1]
+        num_classes = unique_classes.shape[0]
+
+        confusion_matrix = np.zeros((num_classes, num_thresholds, 3))
+        for class_idx, class_id in enumerate(unique_classes):
+            is_class = sorted_prediction_class_ids == class_id
+            num_true = class_counts[class_idx]
+            num_predictions = is_class.sum()
+
+            if num_predictions == 0:
+                true_positives = np.zeros(num_thresholds)
+                false_positives = np.zeros(num_thresholds)
+                false_negatives = np.full(num_thresholds, num_true)
+            elif num_true == 0:
+                true_positives = np.zeros(num_thresholds)
+                false_positives = np.full(num_thresholds, num_predictions)
+                false_negatives = np.zeros(num_thresholds)
+            else:
+                true_positives = sorted_matches[is_class].sum(0)
+                false_positives = (1 - sorted_matches[is_class]).sum(0)
+                false_negatives = num_true - true_positives
+            confusion_matrix[class_idx] = np.stack(
+                [true_positives, false_positives, false_negatives], axis=1
+            )
+
+        return confusion_matrix
+
+    @staticmethod
+    def _compute_f1(confusion_matrix: np.ndarray) -> np.ndarray:
+        """
+        Broadcastable function, computing the F1 score from the confusion matrix.
+
+        Arguments:
+            confusion_matrix: np.ndarray, shape (N, ..., 3), where the last dimension
+                contains the true positives, false positives, and false negatives.
+
+        Returns:
+            np.ndarray, shape (N, ...), containing the F1 score for each element.
+        """
+        if not confusion_matrix.shape[-1] == 3:
+            raise ValueError(
+                f"Confusion matrix must have shape (..., 3), got "
+                f"{confusion_matrix.shape}"
+            )
+        true_positives = confusion_matrix[..., 0]
+        false_positives = confusion_matrix[..., 1]
+        false_negatives = confusion_matrix[..., 2]
+
+        # Alternate formula, avoids multiple zero division checks
+        denominator = 2 * true_positives + false_positives + false_negatives
+        f1_score = np.where(denominator == 0, 0, 2 * true_positives / denominator)
+
+        return f1_score
+
+    def _detections_content(self, detections: Detections) -> np.ndarray:
+        """Return boxes, masks or oriented bounding boxes from detections."""
+        if self._metric_target == MetricTarget.BOXES:
+            return detections.xyxy
+        if self._metric_target == MetricTarget.MASKS:
+            return (
+                detections.mask
+                if detections.mask is not None
+                else np.empty((0, 0, 0), dtype=bool)
+            )
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            if obb := detections.data.get(ORIENTED_BOX_COORDINATES):
+                return np.ndarray(obb, dtype=np.float32)
+            return np.empty((0, 8), dtype=np.float32)
+        raise ValueError(f"Invalid metric target: {self._metric_target}")
+
+    def _filter_detections_by_size(
+        self, detections: Detections, size_category: ObjectSizeCategory
+    ) -> Detections:
+        """Return a copy of detections with contents filtered by object size."""
+        new_detections = deepcopy(detections)
+        if detections.is_empty() or size_category == ObjectSizeCategory.ANY:
+            return new_detections
+
+        sizes = get_detection_size_category(new_detections, self._metric_target)
+        size_mask = sizes == size_category.value
+
+        new_detections.xyxy = new_detections.xyxy[size_mask]
+        if new_detections.mask is not None:
+            new_detections.mask = new_detections.mask[size_mask]
+        if new_detections.class_id is not None:
+            new_detections.class_id = new_detections.class_id[size_mask]
+        if new_detections.confidence is not None:
+            new_detections.confidence = new_detections.confidence[size_mask]
+        if new_detections.tracker_id is not None:
+            new_detections.tracker_id = new_detections.tracker_id[size_mask]
+        if new_detections.data is not None:
+            for key, value in new_detections.data.items():
+                new_detections.data[key] = np.array(value)[size_mask]
+
+        return new_detections
+
+    def _filter_predictions_and_targets_by_size(
+        self,
+        predictions_list: List[Detections],
+        targets_list: List[Detections],
+        size_category: ObjectSizeCategory,
+    ) -> Tuple[List[Detections], List[Detections]]:
+        """
+        Filter predictions and targets by object size category.
+        """
+        new_predictions_list = []
+        new_targets_list = []
+        for predictions, targets in zip(predictions_list, targets_list):
+            new_predictions_list.append(
+                self._filter_detections_by_size(predictions, size_category)
+            )
+            new_targets_list.append(
+                self._filter_detections_by_size(targets, size_category)
+            )
+        return new_predictions_list, new_targets_list
+
+
+@dataclass
+class F1ScoreResult:
+    """
+    The results of the F1 score metric calculation.
+
+    Defaults to `0` if no detections or targets were provided.
+    Provides a custom `__str__` method for pretty printing.
+
+    Attributes:
+        metric_target (MetricTarget): the type of data used for the metric -
+            boxes, masks or oriented bounding boxes.
+        averaging_method (AveragingMethod): the averaging method used to compute the
+            F1 scores. Determines how the F1 scores are aggregated across classes.
+        f1_50 (float): the F1 score at IoU threshold of `0.5`.
+        f1_75 (float): the F1 score at IoU threshold of `0.75`.
+        f1_scores (np.ndarray): the F1 scores at each IoU threshold.
+            Shape: `(num_iou_thresholds,)`
+        f1_per_class (np.ndarray): the F1 scores per class and IoU threshold.
+            Shape: `(num_target_classes, num_iou_thresholds)`
+        iou_thresholds (np.ndarray): the IoU thresholds used in the calculations.
+        matched_classes (np.ndarray): the class IDs of all matched classes.
+            Corresponds to the rows of `f1_per_class`.
+        small_objects (Optional[F1ScoreResult]): the F1 metric results
+            for small objects.
+        medium_objects (Optional[F1ScoreResult]): the F1 metric results
+            for medium objects.
+        large_objects (Optional[F1ScoreResult]): the F1 metric results
+            for large objects.
+    """
+
+    metric_target: MetricTarget
+    averaging_method: AveragingMethod
+
+    @property
+    def f1_50(self) -> float:
+        return self.f1_scores[0]
+
+    @property
+    def f1_75(self) -> float:
+        return self.f1_scores[5]
+
+    f1_scores: np.ndarray
+    f1_per_class: np.ndarray
+    iou_thresholds: np.ndarray
+    matched_classes: np.ndarray
+
+    small_objects: Optional[F1ScoreResult]
+    medium_objects: Optional[F1ScoreResult]
+    large_objects: Optional[F1ScoreResult]
+
+    def __str__(self) -> str:
+        """
+        Format as a pretty string.
+
+        Example:
+            ```python
+            print(f1_result)
+            ```
+        """
+        out_str = (
+            f"{self.__class__.__name__}:\n"
+            f"Metric target: {self.metric_target}\n"
+            f"Averaging method: {self.averaging_method}\n"
+            f"F1 @ 50:     {self.f1_50:.4f}\n"
+            f"F1 @ 75:     {self.f1_75:.4f}\n"
+            f"F1 @ thresh: {self.f1_scores}\n"
+            f"IoU thresh:  {self.iou_thresholds}\n"
+            f"F1 per class:\n"
+        )
+        if self.f1_per_class.size == 0:
+            out_str += "  No results\n"
+        for class_id, f1_of_class in zip(self.matched_classes, self.f1_per_class):
+            out_str += f"  {class_id}: {f1_of_class}\n"
+
+        indent = "  "
+        if self.small_objects is not None:
+            indented = indent + str(self.small_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nSmall objects:\n{indented}"
+        if self.medium_objects is not None:
+            indented = indent + str(self.medium_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nMedium objects:\n{indented}"
+        if self.large_objects is not None:
+            indented = indent + str(self.large_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nLarge objects:\n{indented}"
+
+        return out_str
+
+    def to_pandas(self) -> "pd.DataFrame":
+        """
+        Convert the result to a pandas DataFrame.
+
+        Returns:
+            (pd.DataFrame): The result as a DataFrame.
+        """
+        ensure_pandas_installed()
+        import pandas as pd
+
+        pandas_data = {
+            "F1@50": self.f1_50,
+            "F1@75": self.f1_75,
+        }
+
+        if self.small_objects is not None:
+            small_objects_df = self.small_objects.to_pandas()
+            for key, value in small_objects_df.items():
+                pandas_data[f"small_objects_{key}"] = value
+        if self.medium_objects is not None:
+            medium_objects_df = self.medium_objects.to_pandas()
+            for key, value in medium_objects_df.items():
+                pandas_data[f"medium_objects_{key}"] = value
+        if self.large_objects is not None:
+            large_objects_df = self.large_objects.to_pandas()
+            for key, value in large_objects_df.items():
+                pandas_data[f"large_objects_{key}"] = value
+
+        return pd.DataFrame(pandas_data, index=[0])
+
+    def plot(self):
+        """
+        Plot the F1 results.
+        """
+
+        labels = ["F1@50", "F1@75"]
+        values = [self.f1_50, self.f1_75]
+        colors = [LEGACY_COLOR_PALETTE[0]] * 2
+
+        if self.small_objects is not None:
+            small_objects = self.small_objects
+            labels += ["Small: F1@50", "Small: F1@75"]
+            values += [small_objects.f1_50, small_objects.f1_75]
+            colors += [LEGACY_COLOR_PALETTE[3]] * 2
+
+        if self.medium_objects is not None:
+            medium_objects = self.medium_objects
+            labels += ["Medium: F1@50", "Medium: F1@75"]
+            values += [medium_objects.f1_50, medium_objects.f1_75]
+            colors += [LEGACY_COLOR_PALETTE[2]] * 2
+
+        if self.large_objects is not None:
+            large_objects = self.large_objects
+            labels += ["Large: F1@50", "Large: F1@75"]
+            values += [large_objects.f1_50, large_objects.f1_75]
+            colors += [LEGACY_COLOR_PALETTE[4]] * 2
+
+        plt.rcParams["font.family"] = "monospace"
+
+        _, ax = plt.subplots(figsize=(10, 6))
+        ax.set_ylim(0, 1)
+        ax.set_ylabel("Value", fontweight="bold")
+        title = (
+            f"F1 Score, by Object Size"
+            f"\n(target: {self.metric_target.value},"
+            f" averaging: {self.averaging_method.value})"
+        )
+        ax.set_title(title, fontweight="bold")
+
+        x_positions = range(len(labels))
+        bars = ax.bar(x_positions, values, color=colors, align="center")
+
+        ax.set_xticks(x_positions)
+        ax.set_xticklabels(labels, rotation=45, ha="right")
+
+        for bar in bars:
+            y_value = bar.get_height()
+            ax.text(
+                bar.get_x() + bar.get_width() / 2,
+                y_value + 0.02,
+                f"{y_value:.2f}",
+                ha="center",
+                va="bottom",
+            )
+
+        plt.rcParams["font.family"] = "sans-serif"
+
+        plt.tight_layout()
+        plt.show()

supervision/metrics/mean_average_precision.py

@@ -0,0 +1,562 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List, Optional, Tuple, Union
+
+import numpy as np
+from matplotlib import pyplot as plt
+
+from supervision.config import ORIENTED_BOX_COORDINATES
+from supervision.detection.core import Detections
+from supervision.detection.utils import box_iou_batch, mask_iou_batch
+from supervision.draw.color import LEGACY_COLOR_PALETTE
+from supervision.metrics.core import Metric, MetricTarget
+from supervision.metrics.utils.object_size import (
+    ObjectSizeCategory,
+    get_detection_size_category,
+)
+from supervision.metrics.utils.utils import ensure_pandas_installed
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class MeanAveragePrecision(Metric):
+    def __init__(
+        self,
+        metric_target: MetricTarget = MetricTarget.BOXES,
+        class_agnostic: bool = False,
+    ):
+        """
+        Initialize the Mean Average Precision metric.
+
+        Args:
+            metric_target (MetricTarget): The type of detection data to use.
+            class_agnostic (bool): Whether to treat all data as a single class.
+        """
+        self._metric_target = metric_target
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            raise NotImplementedError(
+                "Mean Average Precision is not implemented for oriented bounding boxes."
+            )
+
+        self._class_agnostic = class_agnostic
+
+        self._predictions_list: List[Detections] = []
+        self._targets_list: List[Detections] = []
+
+    def reset(self) -> None:
+        self._predictions_list = []
+        self._targets_list = []
+
+    def update(
+        self,
+        predictions: Union[Detections, List[Detections]],
+        targets: Union[Detections, List[Detections]],
+    ) -> MeanAveragePrecision:
+        """
+        Add new predictions and targets to the metric, but do not compute the result.
+
+        Args:
+            predictions (Union[Detections, List[Detections]]): The predicted detections.
+            targets (Union[Detections, List[Detections]]): The ground-truth detections.
+
+        Returns:
+            (MeanAveragePrecision): The updated metric instance.
+        """
+        if not isinstance(predictions, list):
+            predictions = [predictions]
+        if not isinstance(targets, list):
+            targets = [targets]
+
+        if len(predictions) != len(targets):
+            raise ValueError(
+                f"The number of predictions ({len(predictions)}) and"
+                f" targets ({len(targets)}) during the update must be the same."
+            )
+
+        self._predictions_list.extend(predictions)
+        self._targets_list.extend(targets)
+
+        return self
+
+    def compute(
+        self,
+    ) -> MeanAveragePrecisionResult:
+        """
+        Calculate Mean Average Precision based on predicted and ground-truth
+            detections at different thresholds.
+
+        Returns:
+            (MeanAveragePrecisionResult): New instance of MeanAveragePrecision.
+
+        Example:
+            ```python
+            import supervision as sv
+            from supervision.metrics import MeanAveragePrecision
+
+            predictions = sv.Detections(...)
+            targets = sv.Detections(...)
+
+            map_metric = MeanAveragePrecision()
+            map_result = map_metric.update(predictions, targets).compute()
+
+            print(map_result)
+            print(map_result.map50_95)
+            map_result.plot()
+            ```
+        """
+        result = self._compute(self._predictions_list, self._targets_list)
+
+        small_predictions = []
+        small_targets = []
+        for predictions, targets in zip(self._predictions_list, self._targets_list):
+            small_predictions.append(
+                self._filter_detections_by_size(predictions, ObjectSizeCategory.SMALL)
+            )
+            small_targets.append(
+                self._filter_detections_by_size(targets, ObjectSizeCategory.SMALL)
+            )
+        result.small_objects = self._compute(small_predictions, small_targets)
+
+        medium_predictions = []
+        medium_targets = []
+        for predictions, targets in zip(self._predictions_list, self._targets_list):
+            medium_predictions.append(
+                self._filter_detections_by_size(predictions, ObjectSizeCategory.MEDIUM)
+            )
+            medium_targets.append(
+                self._filter_detections_by_size(targets, ObjectSizeCategory.MEDIUM)
+            )
+        result.medium_objects = self._compute(medium_predictions, medium_targets)
+
+        large_predictions = []
+        large_targets = []
+        for predictions, targets in zip(self._predictions_list, self._targets_list):
+            large_predictions.append(
+                self._filter_detections_by_size(predictions, ObjectSizeCategory.LARGE)
+            )
+            large_targets.append(
+                self._filter_detections_by_size(targets, ObjectSizeCategory.LARGE)
+            )
+        result.large_objects = self._compute(large_predictions, large_targets)
+
+        return result
+
+    def _compute(
+        self,
+        predictions_list: List[Detections],
+        targets_list: List[Detections],
+    ) -> MeanAveragePrecisionResult:
+        iou_thresholds = np.linspace(0.5, 0.95, 10)
+        stats = []
+
+        for predictions, targets in zip(predictions_list, targets_list):
+            prediction_contents = self._detections_content(predictions)
+            target_contents = self._detections_content(targets)
+
+            if len(targets) > 0:
+                if len(predictions) == 0:
+                    stats.append(
+                        (
+                            np.zeros((0, iou_thresholds.size), dtype=bool),
+                            np.zeros((0,), dtype=np.float32),
+                            np.zeros((0,), dtype=int),
+                            targets.class_id,
+                        )
+                    )
+
+                else:
+                    if self._metric_target == MetricTarget.BOXES:
+                        iou = box_iou_batch(target_contents, prediction_contents)
+                    elif self._metric_target == MetricTarget.MASKS:
+                        iou = mask_iou_batch(target_contents, prediction_contents)
+                    else:
+                        raise NotImplementedError(
+                            "Unsupported metric target for IoU calculation"
+                        )
+
+                    matches = self._match_detection_batch(
+                        predictions.class_id, targets.class_id, iou, iou_thresholds
+                    )
+                    stats.append(
+                        (
+                            matches,
+                            predictions.confidence,
+                            predictions.class_id,
+                            targets.class_id,
+                        )
+                    )
+
+        # Compute average precisions if any matches exist
+        if stats:
+            concatenated_stats = [np.concatenate(items, 0) for items in zip(*stats)]
+            average_precisions, unique_classes = self._average_precisions_per_class(
+                *concatenated_stats
+            )
+            mAP_scores = np.mean(average_precisions, axis=0)
+        else:
+            mAP_scores = np.zeros((10,), dtype=np.float32)
+            unique_classes = np.empty((0,), dtype=int)
+            average_precisions = np.empty((0, len(iou_thresholds)), dtype=np.float32)
+
+        return MeanAveragePrecisionResult(
+            metric_target=self._metric_target,
+            mAP_scores=mAP_scores,
+            iou_thresholds=iou_thresholds,
+            matched_classes=unique_classes,
+            ap_per_class=average_precisions,
+        )
+
+    @staticmethod
+    def _compute_average_precision(recall: np.ndarray, precision: np.ndarray) -> float:
+        """
+        Compute the average precision using 101-point interpolation (COCO), given
+            the recall and precision curves.
+
+        Args:
+            recall (np.ndarray): The recall curve.
+            precision (np.ndarray): The precision curve.
+
+        Returns:
+            (float): Average precision.
+        """
+        if len(recall) == 0 and len(precision) == 0:
+            return 0.0
+
+        recall_levels = np.linspace(0, 1, 101)
+        precision_levels = np.zeros_like(recall_levels)
+        for r, p in zip(recall[::-1], precision[::-1]):
+            precision_levels[recall_levels <= r] = p
+
+        average_precision = (1 / 100 * precision_levels).sum()
+        return average_precision
+
+    @staticmethod
+    def _match_detection_batch(
+        predictions_classes: np.ndarray,
+        target_classes: np.ndarray,
+        iou: np.ndarray,
+        iou_thresholds: np.ndarray,
+    ) -> np.ndarray:
+        num_predictions, num_iou_levels = (
+            predictions_classes.shape[0],
+            iou_thresholds.shape[0],
+        )
+        correct = np.zeros((num_predictions, num_iou_levels), dtype=bool)
+        correct_class = target_classes[:, None] == predictions_classes
+
+        for i, iou_level in enumerate(iou_thresholds):
+            matched_indices = np.where((iou >= iou_level) & correct_class)
+
+            if matched_indices[0].shape[0]:
+                combined_indices = np.stack(matched_indices, axis=1)
+                iou_values = iou[matched_indices][:, None]
+                matches = np.hstack([combined_indices, iou_values])
+
+                if matched_indices[0].shape[0] > 1:
+                    matches = matches[matches[:, 2].argsort()[::-1]]
+                    matches = matches[np.unique(matches[:, 1], return_index=True)[1]]
+                    matches = matches[np.unique(matches[:, 0], return_index=True)[1]]
+
+                correct[matches[:, 1].astype(int), i] = True
+
+        return correct
+
+    @staticmethod
+    def _average_precisions_per_class(
+        matches: np.ndarray,
+        prediction_confidence: np.ndarray,
+        prediction_class_ids: np.ndarray,
+        true_class_ids: np.ndarray,
+    ) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Compute the average precision, given the recall and precision curves.
+        Source: https://github.com/rafaelpadilla/Object-Detection-Metrics.
+
+        Args:
+            matches (np.ndarray): True positives.
+            prediction_confidence (np.ndarray): Objectness value from 0-1.
+            prediction_class_ids (np.ndarray): Predicted object classes.
+            true_class_ids (np.ndarray): True object classes.
+            eps (float, optional): Small value to prevent division by zero.
+
+        Returns:
+            (Tuple[np.ndarray, np.ndarray]): Average precision for different
+                IoU levels, and an array of class IDs that were matched.
+        """
+        eps = 1e-16
+
+        sorted_indices = np.argsort(-prediction_confidence)
+        matches = matches[sorted_indices]
+        prediction_class_ids = prediction_class_ids[sorted_indices]
+
+        unique_classes, class_counts = np.unique(true_class_ids, return_counts=True)
+        num_classes = unique_classes.shape[0]
+
+        average_precisions = np.zeros((num_classes, matches.shape[1]))
+
+        for class_idx, class_id in enumerate(unique_classes):
+            is_class = prediction_class_ids == class_id
+            total_true = class_counts[class_idx]
+            total_prediction = is_class.sum()
+
+            if total_prediction == 0 or total_true == 0:
+                continue
+
+            false_positives = (1 - matches[is_class]).cumsum(0)
+            true_positives = matches[is_class].cumsum(0)
+            false_negatives = total_true - true_positives
+
+            recall = true_positives / (true_positives + false_negatives + eps)
+            precision = true_positives / (true_positives + false_positives)
+
+            for iou_level_idx in range(matches.shape[1]):
+                average_precisions[class_idx, iou_level_idx] = (
+                    MeanAveragePrecision._compute_average_precision(
+                        recall[:, iou_level_idx], precision[:, iou_level_idx]
+                    )
+                )
+
+        return average_precisions, unique_classes
+
+    def _detections_content(self, detections: Detections) -> np.ndarray:
+        """Return boxes, masks or oriented bounding boxes from detections."""
+        if self._metric_target == MetricTarget.BOXES:
+            return detections.xyxy
+        if self._metric_target == MetricTarget.MASKS:
+            return (
+                detections.mask
+                if detections.mask is not None
+                else self._make_empty_content()
+            )
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            if obb := detections.data.get(ORIENTED_BOX_COORDINATES):
+                return np.ndarray(obb, dtype=np.float32)
+            return self._make_empty_content()
+        raise ValueError(f"Invalid metric target: {self._metric_target}")
+
+    def _make_empty_content(self) -> np.ndarray:
+        if self._metric_target == MetricTarget.BOXES:
+            return np.empty((0, 4), dtype=np.float32)
+        if self._metric_target == MetricTarget.MASKS:
+            return np.empty((0, 0, 0), dtype=bool)
+        if self._metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+            return np.empty((0, 8), dtype=np.float32)
+        raise ValueError(f"Invalid metric target: {self._metric_target}")
+
+    def _filter_detections_by_size(
+        self, detections: Detections, size_category: ObjectSizeCategory
+    ) -> Detections:
+        """Return a copy of detections with contents filtered by object size."""
+        new_detections = deepcopy(detections)
+        if detections.is_empty() or size_category == ObjectSizeCategory.ANY:
+            return new_detections
+
+        sizes = get_detection_size_category(new_detections, self._metric_target)
+        size_mask = sizes == size_category.value
+
+        new_detections.xyxy = new_detections.xyxy[size_mask]
+        if new_detections.mask is not None:
+            new_detections.mask = new_detections.mask[size_mask]
+        if new_detections.class_id is not None:
+            new_detections.class_id = new_detections.class_id[size_mask]
+        if new_detections.confidence is not None:
+            new_detections.confidence = new_detections.confidence[size_mask]
+        if new_detections.tracker_id is not None:
+            new_detections.tracker_id = new_detections.tracker_id[size_mask]
+        if new_detections.data is not None:
+            for key, value in new_detections.data.items():
+                new_detections.data[key] = np.array(value)[size_mask]
+
+        return new_detections
+
+
+@dataclass
+class MeanAveragePrecisionResult:
+    """
+    The result of the Mean Average Precision calculation.
+
+    Defaults to `0` when no detections or targets are present.
+
+    Attributes:
+        metric_target (MetricTarget): the type of data used for the metric -
+            boxes, masks or oriented bounding boxes.
+        mAP_map50_95 (float): the mAP score at IoU thresholds from `0.5` to `0.95`.
+        mAP_map50 (float): the mAP score at IoU threshold of `0.5`.
+        mAP_map75 (float): the mAP score at IoU threshold of `0.75`.
+        mAP_scores (np.ndarray): the mAP scores at each IoU threshold.
+            Shape: `(num_iou_thresholds,)`
+        ap_per_class (np.ndarray): the average precision scores per
+            class and IoU threshold. Shape: `(num_target_classes, num_iou_thresholds)`
+        iou_thresholds (np.ndarray): the IoU thresholds used in the calculations.
+        matched_classes (np.ndarray): the class IDs of all matched classes.
+            Corresponds to the rows of `ap_per_class`.
+        small_objects (Optional[MeanAveragePrecisionResult]): the mAP results
+            for small objects.
+        medium_objects (Optional[MeanAveragePrecisionResult]): the mAP results
+            for medium objects.
+        large_objects (Optional[MeanAveragePrecisionResult]): the mAP results
+            for large objects.
+    """
+
+    metric_target: MetricTarget
+
+    @property
+    def map50_95(self) -> float:
+        return self.mAP_scores.mean()
+
+    @property
+    def map50(self) -> float:
+        return self.mAP_scores[0]
+
+    @property
+    def map75(self) -> float:
+        return self.mAP_scores[5]
+
+    mAP_scores: np.ndarray
+    ap_per_class: np.ndarray
+    iou_thresholds: np.ndarray
+    matched_classes: np.ndarray
+    small_objects: Optional[MeanAveragePrecisionResult] = None
+    medium_objects: Optional[MeanAveragePrecisionResult] = None
+    large_objects: Optional[MeanAveragePrecisionResult] = None
+
+    def __str__(self) -> str:
+        """
+        Format as a pretty string.
+
+        Example:
+            ```python
+            print(map_result)
+            ```
+        """
+
+        out_str = (
+            f"{self.__class__.__name__}:\n"
+            f"Metric target: {self.metric_target}\n"
+            f"mAP @ 50:95: {self.map50_95:.4f}\n"
+            f"mAP @ 50:    {self.map50:.4f}\n"
+            f"mAP @ 75:    {self.map75:.4f}\n"
+            f"mAP scores: {self.mAP_scores}\n"
+            f"IoU thresh: {self.iou_thresholds}\n"
+            f"AP per class:\n"
+        )
+        if self.ap_per_class.size == 0:
+            out_str += "  No results\n"
+        for class_id, ap_of_class in zip(self.matched_classes, self.ap_per_class):
+            out_str += f"  {class_id}: {ap_of_class}\n"
+
+        indent = "  "
+        if self.small_objects is not None:
+            indented = indent + str(self.small_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nSmall objects:\n{indented}"
+        if self.medium_objects is not None:
+            indented = indent + str(self.medium_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nMedium objects:\n{indented}"
+        if self.large_objects is not None:
+            indented = indent + str(self.large_objects).replace("\n", f"\n{indent}")
+            out_str += f"\nLarge objects:\n{indented}"
+
+        return out_str
+
+    def to_pandas(self) -> "pd.DataFrame":
+        """
+        Convert the result to a pandas DataFrame.
+
+        Returns:
+            (pd.DataFrame): The result as a DataFrame.
+        """
+        ensure_pandas_installed()
+        import pandas as pd
+
+        pandas_data = {
+            "mAP@50:95": self.map50_95,
+            "mAP@50": self.map50,
+            "mAP@75": self.map75,
+        }
+
+        if self.small_objects is not None:
+            small_objects_df = self.small_objects.to_pandas()
+            for key, value in small_objects_df.items():
+                pandas_data[f"small_objects_{key}"] = value
+        if self.medium_objects is not None:
+            medium_objects_df = self.medium_objects.to_pandas()
+            for key, value in medium_objects_df.items():
+                pandas_data[f"medium_objects_{key}"] = value
+        if self.large_objects is not None:
+            large_objects_df = self.large_objects.to_pandas()
+            for key, value in large_objects_df.items():
+                pandas_data[f"large_objects_{key}"] = value
+
+        # Average precisions are currently not included in the DataFrame.
+
+        return pd.DataFrame(
+            pandas_data,
+            index=[0],
+        )
+
+    def plot(self):
+        """
+        Plot the mAP results.
+        """
+
+        labels = ["mAP@50:95", "mAP@50", "mAP@75"]
+        values = [self.map50_95, self.map50, self.map75]
+        colors = [LEGACY_COLOR_PALETTE[0]] * 3
+
+        if self.small_objects is not None:
+            labels += ["Small: mAP@50:95", "Small: mAP@50", "Small: mAP@75"]
+            values += [
+                self.small_objects.map50_95,
+                self.small_objects.map50,
+                self.small_objects.map75,
+            ]
+            colors += [LEGACY_COLOR_PALETTE[3]] * 3
+
+        if self.medium_objects is not None:
+            labels += ["Medium: mAP@50:95", "Medium: mAP@50", "Medium: mAP@75"]
+            values += [
+                self.medium_objects.map50_95,
+                self.medium_objects.map50,
+                self.medium_objects.map75,
+            ]
+            colors += [LEGACY_COLOR_PALETTE[2]] * 3
+
+        if self.large_objects is not None:
+            labels += ["Large: mAP@50:95", "Large: mAP@50", "Large: mAP@75"]
+            values += [
+                self.large_objects.map50_95,
+                self.large_objects.map50,
+                self.large_objects.map75,
+            ]
+            colors += [LEGACY_COLOR_PALETTE[4]] * 3
+
+        plt.rcParams["font.family"] = "monospace"
+
+        _, ax = plt.subplots(figsize=(10, 6))
+        ax.set_ylim(0, 1)
+        ax.set_ylabel("Value", fontweight="bold")
+        ax.set_title("Mean Average Precision", fontweight="bold")
+
+        x_positions = range(len(labels))
+        bars = ax.bar(x_positions, values, color=colors, align="center")
+
+        ax.set_xticks(x_positions)
+        ax.set_xticklabels(labels, rotation=45, ha="right")
+
+        for bar in bars:
+            y_value = bar.get_height()
+            ax.text(
+                bar.get_x() + bar.get_width() / 2,
+                y_value + 0.02,
+                f"{y_value:.2f}",
+                ha="center",
+                va="bottom",
+            )
+
+        plt.rcParams["font.family"] = "sans-serif"
+
+        plt.tight_layout()
+        plt.show()

supervision/metrics/utils/object_size.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+import numpy as np
+import numpy.typing as npt
+
+from supervision.config import ORIENTED_BOX_COORDINATES
+from supervision.metrics.core import MetricTarget
+
+if TYPE_CHECKING:
+    from supervision.detection.core import Detections
+
+SIZE_THRESHOLDS = (32**2, 96**2)
+
+
+class ObjectSizeCategory(Enum):
+    ANY = -1
+    SMALL = 1
+    MEDIUM = 2
+    LARGE = 3
+
+
+def get_object_size_category(
+    data: npt.NDArray, metric_target: MetricTarget
+) -> npt.NDArray[np.int_]:
+    """
+    Get the size category of an object. Distinguish based on the metric target.
+
+    Args:
+        data (np.ndarray): The object data, shaped (N, ...).
+        metric_target (MetricTarget): Determines whether boxes, masks or
+            oriented bounding boxes are used.
+
+    Returns:
+        (np.ndarray) The size category of each object, matching
+        the enum values of ObjectSizeCategory. Shaped (N,).
+    """
+    if metric_target == MetricTarget.BOXES:
+        return get_bbox_size_category(data)
+    if metric_target == MetricTarget.MASKS:
+        return get_mask_size_category(data)
+    if metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+        return get_obb_size_category(data)
+    raise ValueError("Invalid metric type")
+
+
+def get_bbox_size_category(xyxy: npt.NDArray[np.float32]) -> npt.NDArray[np.int_]:
+    """
+    Get the size category of a bounding boxes array.
+
+    Args:
+        xyxy (np.ndarray): The bounding boxes array shaped (N, 4).
+
+    Returns:
+        (np.ndarray) The size category of each bounding box, matching
+        the enum values of ObjectSizeCategory. Shaped (N,).
+    """
+    if len(xyxy.shape) != 2 or xyxy.shape[1] != 4:
+        raise ValueError("Bounding boxes must be shaped (N, 4)")
+
+    width = xyxy[:, 2] - xyxy[:, 0]
+    height = xyxy[:, 3] - xyxy[:, 1]
+    areas = width * height
+
+    result = np.full(areas.shape, ObjectSizeCategory.ANY.value)
+    SM, LG = SIZE_THRESHOLDS
+    result[areas < SM] = ObjectSizeCategory.SMALL.value
+    result[(areas >= SM) & (areas < LG)] = ObjectSizeCategory.MEDIUM.value
+    result[areas >= LG] = ObjectSizeCategory.LARGE.value
+    return result
+
+
+def get_mask_size_category(mask: npt.NDArray[np.bool_]) -> npt.NDArray[np.int_]:
+    """
+    Get the size category of detection masks.
+
+    Args:
+        mask (np.ndarray): The mask array shaped (N, H, W).
+
+    Returns:
+        (np.ndarray) The size category of each mask, matching
+        the enum values of ObjectSizeCategory. Shaped (N,).
+    """
+    if len(mask.shape) != 3:
+        raise ValueError("Masks must be shaped (N, H, W)")
+
+    areas = np.sum(mask, axis=(1, 2))
+
+    result = np.full(areas.shape, ObjectSizeCategory.ANY.value)
+    SM, LG = SIZE_THRESHOLDS
+    result[areas < SM] = ObjectSizeCategory.SMALL.value
+    result[(areas >= SM) & (areas < LG)] = ObjectSizeCategory.MEDIUM.value
+    result[areas >= LG] = ObjectSizeCategory.LARGE.value
+    return result
+
+
+def get_obb_size_category(xyxyxyxy: npt.NDArray[np.float32]) -> npt.NDArray[np.int_]:
+    """
+    Get the size category of a oriented bounding boxes array.
+
+    Args:
+        xyxyxyxy (np.ndarray): The bounding boxes array shaped (N, 4, 2).
+
+    Returns:
+        (np.ndarray) The size category of each bounding box, matching
+        the enum values of ObjectSizeCategory. Shaped (N,).
+    """
+    if len(xyxyxyxy.shape) != 3 or xyxyxyxy.shape[1] != 4 or xyxyxyxy.shape[2] != 2:
+        raise ValueError("Oriented bounding boxes must be shaped (N, 4, 2)")
+
+    # Shoelace formula
+    x = xyxyxyxy[:, :, 0]
+    y = xyxyxyxy[:, :, 1]
+    x1, x2, x3, x4 = x.T
+    y1, y2, y3, y4 = y.T
+    areas = 0.5 * np.abs(
+        (x1 * y2 + x2 * y3 + x3 * y4 + x4 * y1)
+        - (x2 * y1 + x3 * y2 + x4 * y3 + x1 * y4)
+    )
+
+    result = np.full(areas.shape, ObjectSizeCategory.ANY.value)
+    SM, LG = SIZE_THRESHOLDS
+    result[areas < SM] = ObjectSizeCategory.SMALL.value
+    result[(areas >= SM) & (areas < LG)] = ObjectSizeCategory.MEDIUM.value
+    result[areas >= LG] = ObjectSizeCategory.LARGE.value
+    return result
+
+
+def get_detection_size_category(
+    detections: Detections, metric_target: MetricTarget = MetricTarget.BOXES
+) -> npt.NDArray[np.int_]:
+    """
+    Get the size category of a detections object.
+
+    Args:
+        xyxyxyxy (np.ndarray): The bounding boxes array shaped (N, 8).
+        metric_target (MetricTarget): Determines whether boxes, masks or
+            oriented bounding boxes are used.
+
+    Returns:
+        (np.ndarray) The size category of each bounding box, matching
+        the enum values of ObjectSizeCategory. Shaped (N,).
+    """
+    if metric_target == MetricTarget.BOXES:
+        return get_bbox_size_category(detections.xyxy)
+    if metric_target == MetricTarget.MASKS:
+        if detections.mask is None:
+            raise ValueError("Detections mask is not available")
+        return get_mask_size_category(detections.mask)
+    if metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
+        if detections.data.get(ORIENTED_BOX_COORDINATES) is None:
+            raise ValueError("Detections oriented bounding boxes are not available")
+        return get_obb_size_category(
+            np.array(detections.data[ORIENTED_BOX_COORDINATES])
+        )
+    raise ValueError("Invalid metric type")

supervision/metrics/utils/utils.py

@@ -0,0 +1,9 @@
+def ensure_pandas_installed():
+    try:
+        import pandas  # noqa
+    except ImportError:
+        raise ImportError(
+            "`metrics` extra is required to run the function."
+            " Run `pip install 'supervision[metrics]'` or"
+            " `poetry add supervision -E metrics`"
+        )

supervision/tracker/byte_tracker/core.py

@@ -7,7 +7,6 @@ from supervision.detection.utils import box_iou_batch
 from supervision.tracker.byte_tracker import matching
 from supervision.tracker.byte_tracker.basetrack import BaseTrack, TrackState
 from supervision.tracker.byte_tracker.kalman_filter import KalmanFilter
-from supervision.utils.internal import deprecated_parameter
 
 
 class STrack(BaseTrack):
@@ -197,48 +196,24 @@ class ByteTrack:
     </video>
 
     Parameters:
-        track_activation_threshold (float, optional): Detection confidence threshold
+        track_activation_threshold (float): Detection confidence threshold
             for track activation. Increasing track_activation_threshold improves accuracy
             and stability but might miss true detections. Decreasing it increases
             completeness but risks introducing noise and instability.
-        lost_track_buffer (int, optional): Number of frames to buffer when a track is lost.
+        lost_track_buffer (int): Number of frames to buffer when a track is lost.
             Increasing lost_track_buffer enhances occlusion handling, significantly
             reducing the likelihood of track fragmentation or disappearance caused
             by brief detection gaps.
-        minimum_matching_threshold (float, optional): Threshold for matching tracks with detections.
+        minimum_matching_threshold (float): Threshold for matching tracks with detections.
             Increasing minimum_matching_threshold improves accuracy but risks fragmentation.
             Decreasing it improves completeness but risks false positives and drift.
-        frame_rate (int, optional): The frame rate of the video.
-        minimum_consecutive_frames (int, optional): Number of consecutive frames that an object must
+        frame_rate (int): The frame rate of the video.
+        minimum_consecutive_frames (int): Number of consecutive frames that an object must
             be tracked before it is considered a 'valid' track.
             Increasing minimum_consecutive_frames prevents the creation of accidental tracks from
             false detection or double detection, but risks missing shorter tracks.
     """  # noqa: E501 // docs
 
-    @deprecated_parameter(
-        old_parameter="track_buffer",
-        new_parameter="lost_track_buffer",
-        map_function=lambda x: x,
-        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
-        "be remove in `supervision-0.23.0`. Use '{new_parameter}' "
-        "instead.",
-    )
-    @deprecated_parameter(
-        old_parameter="track_thresh",
-        new_parameter="track_activation_threshold",
-        map_function=lambda x: x,
-        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
-        "be remove in `supervision-0.23.0`. Use '{new_parameter}' "
-        "instead.",
-    )
-    @deprecated_parameter(
-        old_parameter="match_thresh",
-        new_parameter="minimum_matching_threshold",
-        map_function=lambda x: x,
-        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
-        "be remove in `supervision-0.23.0`. Use '{new_parameter}' "
-        "instead.",
-    )
     def __init__(
         self,
         track_activation_threshold: float = 0.25,

supervision/utils/image.py

@@ -158,7 +158,7 @@ def resize_image(
             accepting either `numpy.ndarray` or `PIL.Image.Image`.
         resolution_wh (Tuple[int, int]): The target resolution as
             `(width, height)`.
-        keep_aspect_ratio (bool, optional): Flag to maintain the image's original
+        keep_aspect_ratio (bool): Flag to maintain the image's original
             aspect ratio. Defaults to `False`.
 
     Returns:
@@ -270,6 +270,7 @@ def letterbox_image(
 
     ![letterbox_image](https://media.roboflow.com/supervision-docs/letterbox-image.png){ align=center width="800" }
     """  # noqa E501 // docs
+    assert isinstance(image, np.ndarray)
     color = unify_to_bgr(color=color)
     resized_image = resize_image(
         image=image, resolution_wh=resolution_wh, keep_aspect_ratio=True
@@ -279,7 +280,7 @@ def letterbox_image(
     padding_bottom = resolution_wh[1] - height_new - padding_top
     padding_left = (resolution_wh[0] - width_new) // 2
     padding_right = resolution_wh[0] - width_new - padding_left
-    return cv2.copyMakeBorder(
+    image_with_borders = cv2.copyMakeBorder(
         resized_image,
         padding_top,
         padding_bottom,
@@ -289,6 +290,14 @@ def letterbox_image(
         value=color,
     )
 
+    if image.shape[2] == 4:
+        image[:padding_top, :, 3] = 0
+        image[height_new - padding_bottom :, :, 3] = 0
+        image[:, :padding_left, 3] = 0
+        image[:, width_new - padding_right :, 3] = 0
+
+    return image_with_borders
+
 
 def overlay_image(
     image: npt.NDArray[np.uint8],
@@ -341,9 +350,20 @@ def overlay_image(
     crop_x_max = image_width - max((anchor_x + image_width) - scene_width, 0)
     crop_y_max = image_height - max((anchor_y + image_height) - scene_height, 0)
 
-    image[y_min:y_max, x_min:x_max] = overlay[
-        crop_y_min:crop_y_max, crop_x_min:crop_x_max
-    ]
+    if overlay.shape[2] == 4:
+        b, g, r, alpha = cv2.split(
+            overlay[crop_y_min:crop_y_max, crop_x_min:crop_x_max]
+        )
+        alpha = alpha[:, :, None] / 255.0
+        overlay_color = cv2.merge((b, g, r))
+
+        roi = image[y_min:y_max, x_min:x_max]
+        roi[:] = roi * (1 - alpha) + overlay_color * alpha
+        image[y_min:y_max, x_min:x_max] = roi
+    else:
+        image[y_min:y_max, x_min:x_max] = overlay[
+            crop_y_min:crop_y_max, crop_x_min:crop_x_max
+        ]
 
     return image
 
@@ -360,9 +380,9 @@ class ImageSink:
 
         Args:
             target_dir_path (str): The target directory where images will be saved.
-            overwrite (bool, optional): Whether to overwrite the existing directory.
+            overwrite (bool): Whether to overwrite the existing directory.
                 Defaults to False.
-            image_name_pattern (str, optional): The image file name pattern.
+            image_name_pattern (str): The image file name pattern.
                 Defaults to "image_{:05d}.png".
 
         Examples:
@@ -399,7 +419,7 @@ class ImageSink:
         Args:
             image (np.ndarray): The image to be saved. The image must be in BGR color
                 format.
-            image_name (str, optional): The name to use for the saved image.
+            image_name (Optional[str]): The name to use for the saved image.
                 If not provided, a name will be
                 generated using the `image_name_pattern`.
         """

supervision/utils/internal.py

@@ -2,7 +2,7 @@ import functools
 import inspect
 import os
 import warnings
-from typing import Any, Callable, Set
+from typing import Any, Callable, Generic, Optional, Set, TypeVar
 
 
 class SupervisionWarnings(Warning):
@@ -56,9 +56,9 @@ def deprecated_parameter(
     Parameters:
         old_parameter (str): The name of the deprecated parameter.
         new_parameter (str): The name of the parameter that should be used instead.
-        map_function (Callable, optional): A function used to map the value of the old
+        map_function (Callable): A function used to map the value of the old
             parameter to the new parameter. Defaults to the identity function.
-        warning_message (str, optional): The warning message to be displayed when the
+        warning_message (str): The warning message to be displayed when the
             deprecated parameter is used. Defaults to a generic warning message with
             placeholders for the old parameter, new parameter, and function name.
         **message_kwargs: Additional keyword arguments that can be used to customize
@@ -122,7 +122,10 @@ def deprecated(reason: str):
     return decorator
 
 
-class classproperty(property):
+T = TypeVar("T")
+
+
+class classproperty(Generic[T]):
     """
     A decorator that combines @classmethod and @property.
     It allows a method to be accessed as a property of the class,
@@ -134,17 +137,27 @@ class classproperty(property):
             ...
     """
 
-    def __get__(self, owner_self: object, owner_cls: type) -> object:
+    def __init__(self, fget: Callable[..., T]):
+        """
+        Args:
+            The function that is called when the property is accessed.
+        """
+        self.fget = fget
+
+    def __get__(self, owner_self: Any, owner_cls: Optional[type] = None) -> T:
         """
         Override the __get__ method to return the result of the function call.
 
         Args:
-        owner_self: The instance through which the attribute was accessed, or None.
-        owner_cls: The class through which the attribute was accessed.
+            owner_self: The instance through which the attribute was accessed, or None.
+                Irrelevant for class properties.
+            owner_cls: The class through which the attribute was accessed.
 
         Returns:
-        The result of calling the function stored in 'fget' with 'owner_cls'.
+            The result of calling the function stored in 'fget' with 'owner_cls'.
         """
+        if self.fget is None:
+            raise AttributeError("unreadable attribute")
         return self.fget(owner_cls)
 
 

supervision/utils/notebook.py

@@ -17,7 +17,7 @@ def plot_image(
     Args:
         image (ImageType): The frame to be displayed ImageType
              is a flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`.
-        size (Tuple[int, int]): The size of the plot.
+        size (Tuple[int, int]): The size of the plot in inches.
         cmap (str): the colormap to use for single channel images.
 
     Examples:

supervision/utils/video.py

@@ -19,7 +19,7 @@ class VideoInfo:
         width (int): width of the video in pixels
         height (int): height of the video in pixels
         fps (int): frames per second of the video
-        total_frames (int, optional): total number of frames in the video,
+        total_frames (Optional[int]): total number of frames in the video,
             default is None
 
     Examples:
@@ -116,7 +116,9 @@ class VideoSink:
         self.__writer.release()
 
 
-def _validate_and_setup_video(source_path: str, start: int, end: Optional[int]):
+def _validate_and_setup_video(
+    source_path: str, start: int, end: Optional[int], iterative_seek: bool = False
+):
     video = cv2.VideoCapture(source_path)
     if not video.isOpened():
         raise Exception(f"Could not open video at {source_path}")
@@ -125,12 +127,25 @@ def _validate_and_setup_video(source_path: str, start: int, end: Optional[int]):
         raise Exception("Requested frames are outbound")
     start = max(start, 0)
     end = min(end, total_frames) if end is not None else total_frames
-    video.set(cv2.CAP_PROP_POS_FRAMES, start)
+
+    if iterative_seek:
+        while start > 0:
+            success = video.grab()
+            if not success:
+                break
+            start -= 1
+    elif start > 0:
+        video.set(cv2.CAP_PROP_POS_FRAMES, start)
+
     return video, start, end
 
 
 def get_video_frames_generator(
-    source_path: str, stride: int = 1, start: int = 0, end: Optional[int] = None
+    source_path: str,
+    stride: int = 1,
+    start: int = 0,
+    end: Optional[int] = None,
+    iterative_seek: bool = False,
 ) -> Generator[np.ndarray, None, None]:
     """
     Get a generator that yields the frames of the video.
@@ -143,6 +158,9 @@ def get_video_frames_generator(
             video should generate frames
         end (Optional[int]): Indicates the ending position at which video
             should stop generating frames. If None, video will be read to the end.
+        iterative_seek (bool): If True, the generator will seek to the
+            `start` frame by grabbing each frame, which is much slower. This is a
+            workaround for videos that don't open at all when you set the `start` value.
 
     Returns:
         (Generator[np.ndarray, None, None]): A generator that yields the
@@ -156,7 +174,9 @@ def get_video_frames_generator(
             ...
         ```
     """
-    video, start, end = _validate_and_setup_video(source_path, start, end)
+    video, start, end = _validate_and_setup_video(
+        source_path, start, end, iterative_seek
+    )
     frame_position = start
     while True:
         success, frame = video.read()

test/annotators/test_utils.py

@@ -1,5 +1,4 @@
 from contextlib import ExitStack as DoesNotRaise
-from test.test_utils import mock_detections
 from typing import Optional
 
 import numpy as np
@@ -7,6 +6,7 @@ import pytest
 
 from supervision.annotators.utils import ColorLookup, resolve_color_idx
 from supervision.detection.core import Detections
+from test.test_utils import mock_detections
 
 
 @pytest.mark.parametrize(

test/dataset/formats/test_coco.py

@@ -1,5 +1,5 @@
 from contextlib import ExitStack as DoesNotRaise
-from typing import Dict, List, Tuple, Union
+from typing import Dict, List, Optional, Tuple, Union
 
 import numpy as np
 import pytest
@@ -21,7 +21,7 @@ def mock_coco_annotation(
     category_id: int = 0,
     bbox: Tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
     area: float = 0.0,
-    segmentation: Union[List[list], Dict] = None,
+    segmentation: Optional[Union[List[list], Dict]] = None,
     iscrowd: bool = False,
 ) -> dict:
     if not segmentation:
@@ -308,7 +308,7 @@ def test_group_coco_annotations_by_image_id(
                 ),
             ),
             DoesNotRaise(),
-        ),  # two image annotations with mask, one mask as polygon ans second as RLE
+        ),  # two image annotations with mask, one mask as polygon and second as RLE
         (
             [
                 mock_coco_annotation(