Merge pull request #1742 from roboflow/develop

`supervision-0.26.0` release

.github/workflows/poetry-test.yml

@@ -1,45 +0,0 @@
-name: 🔧 Poetry Checks and Test Workflow
-on:
-  push:
-    paths:
-      - "poetry.lock"
-      - "pyproject.toml"
-  pull_request:
-    paths:
-      - "poetry.lock"
-      - "pyproject.toml"
-  workflow_dispatch:
-
-jobs:
-  poetry-tests:
-    name: Poetry install and check
-    timeout-minutes: 10
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - name: 📥 Checkout the repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: 📜 Setup Poetry
-        uses: abatilo/actions-poetry@3765cf608f2d4a72178a9fc5b918668e542b89b1 # v4.0.0
-
-      - name: 🔍 Check the correctness of the project config
-        run: poetry check
-
-      - name: 🚀 Do Install the package Test
-        run: poetry install --with dev --extras metrics
-
-      - name: 🧪 Run the Import test
-        run: poetry run python -c "import supervision; from supervision import assets; from supervision import metrics; print(supervision.__version__)"
-
-      - name: 🧪 Run the Test
-        run: poetry run pytest

.github/workflows/publish-docs.yml

@@ -33,17 +33,27 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+      - name: 🐍 Install uv and set Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba # v6.3.1
         with:
           python-version: ${{ matrix.python-version }}
+          activate-environment: true
 
-      - name: 📜 Setup Poetry
-        uses: abatilo/actions-poetry@3765cf608f2d4a72178a9fc5b918668e542b89b1 # v4.0.0
 
-      - name: 📦 Install dependencies
+      - name: 🔑 Create GitHub App token (mkdocs)
+        id: mkdocs_token
+        uses: actions/create-github-app-token@df432ceedc7162793a195dd1713ff69aefc7379e # v2.0.6
+        with:
+          app-id: ${{ secrets.MKDOCS_APP_ID }}
+          private-key: ${{ secrets.MKDOCS_PEM }}
+          owner: roboflow
+          repositories: mkdocs-material-insiders
+
+      - name: 🏗️ Install dependencies
         run: |
-          poetry install --with=docs
+          uv pip install -r pyproject.toml --group docs
+          # Install mkdocs-material-insiders using the GitHub App token
+          uv pip install "git+https://roboflow:${{ steps.mkdocs_token.outputs.token }}@github.com/roboflow/mkdocs-material-insiders.git@9.5.49-insiders-4.53.14#egg=mkdocs-material[imaging]"
 
       - name: ⚙️ Configure git for github-actions
         run: |
@@ -53,10 +63,10 @@ jobs:
       - name: 🚀 Deploy Development Docs
         if: (github.event_name == 'push' && github.ref == 'refs/heads/develop') || github.event_name == 'workflow_dispatch'
         run: |
-          MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} poetry run mike deploy --push develop
+          MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} uv run mike deploy --push develop
 
       - name: 🚀 Deploy Release Docs
         if: github.event_name == 'release' && github.event.action == 'published'
         run: |
           latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`)
-          MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} poetry run mike deploy --push --update-aliases $latest_tag latest
+          MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} uv run mike deploy --push --update-aliases $latest_tag latest

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

@@ -0,0 +1,47 @@
+name: Publish Supervision Pre-Releases to PyPI
+
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+[0-9]+.[0-9]+a[0-9]"
+      - "[0-9]+.[0-9]+[0-9]+.[0-9]+b[0-9]"
+      - "[0-9]+.[0-9]+[0-9]+.[0-9]+rc[0-9]"
+  workflow_dispatch:
+
+permissions: {} # Explicitly remove all permissions by default
+
+jobs:
+  publish-pre-release:
+    name: Publish Pre-release Package
+    runs-on: ubuntu-latest
+    environment:
+      name: test
+      url: https://pypi.org/project/supervision/
+    timeout-minutes: 10
+    permissions:
+      id-token: write # Required for PyPI publishing
+      contents: read # Required for checkout
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba # v6.3.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
+
+      - name: 🏗️ Build source and wheel distributions
+        run: |
+          uv pip install -r pyproject.toml --group build
+          uv build
+          uv run twine check --strict dist/*
+
+      - name: 🚀 Publish to PyPi
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+        with:
+          attestations: true

.github/workflows/publish-release.yml

@@ -0,0 +1,45 @@
+name: Publish Supervision Releases to PyPI
+
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+[0-9]+.[0-9]"
+  workflow_dispatch:
+
+permissions: {} # Explicitly remove all permissions by default
+
+jobs:
+  publish-release:
+    name: Publish Release Package
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/project/supervision/
+    timeout-minutes: 10
+    permissions:
+      id-token: write # Required for PyPI publishing
+      contents: read # Required for checkout
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba # v6.3.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
+
+      - name: 🏗️ Build source and wheel distributions
+        run: |
+          uv pip install -r pyproject.toml --group build
+          uv build
+          uv run twine check --strict dist/*
+
+      - name: 🚀 Publish to PyPi
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+        with:
+          attestations: true

.github/workflows/publish-test.yml

@@ -1,52 +0,0 @@
-name: Publish Supervision Pre-Releases to PyPI and TestPyPI
-
-on:
-  push:
-    tags:
-      - "[0-9]+.[0-9]+[0-9]+.[0-9]+a[0-9]"
-      - "[0-9]+.[0-9]+[0-9]+.[0-9]+b[0-9]"
-      - "[0-9]+.[0-9]+[0-9]+.[0-9]+rc[0-9]"
-  workflow_dispatch:
-
-permissions: {} # Explicitly remove all permissions by default
-
-jobs:
-  build-and-publish-pre-release:
-    name: Publish  Pre-releasePackage
-    runs-on: ubuntu-latest
-    environment: test
-    timeout-minutes: 10
-    permissions:
-      id-token: write # Required for PyPI publishing
-      contents: read # Required for checkout
-    strategy:
-      matrix:
-        python-version: ["3.10"]
-    steps:
-      - name: 📥 Checkout the repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: 📜 Setup Poetry
-        uses: abatilo/actions-poetry@3765cf608f2d4a72178a9fc5b918668e542b89b1 # v4.0.0
-
-      - name: 🏗️ Build source and wheel distributions
-        run: |
-          poetry install --with=build
-          poetry build
-          poetry run twine check --strict dist/*
-
-      - name: 🚀 Publish to PyPi
-        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
-        with:
-          attestations: true
-
-      - name: 🚀 Publish to Test-PyPi
-        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
-        with:
-          repository-url: https://test.pypi.org/legacy/
-          attestations: true

.github/workflows/publish-testpypi.yml

@@ -0,0 +1,43 @@
+name: Publish Supervision Releases to TestPyPI
+
+on:
+  workflow_dispatch:
+
+permissions: {} # Explicitly remove all permissions by default
+
+jobs:
+  publish-testpypi:
+    name: Publish Release Package
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/project/supervision/
+    timeout-minutes: 10
+    permissions:
+      id-token: write # Required for PyPI publishing
+      contents: read # Required for checkout
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba # v6.3.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
+
+      - name: 🏗️ Build source and wheel distributions
+        run: |
+          uv pip install -r pyproject.toml --group build
+          uv build
+          uv run twine check --strict dist/*
+
+      - name: 🚀 Publish to Test-PyPi
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          attestations: true

.github/workflows/publish.yml

@@ -1,50 +0,0 @@
-name: Publish Supervision Releases to PyPI and TestPyPI
-
-on:
-  push:
-    tags:
-      - "[0-9]+.[0-9]+[0-9]+.[0-9]"
-  workflow_dispatch:
-
-permissions: {} # Explicitly remove all permissions by default
-
-jobs:
-  build-and-publish-pre-release:
-    name: Publish Release Package
-    runs-on: ubuntu-latest
-    environment: release
-    timeout-minutes: 10
-    permissions:
-      id-token: write # Required for PyPI publishing
-      contents: read # Required for checkout
-    strategy:
-      matrix:
-        python-version: ["3.10"]
-    steps:
-      - name: 📥 Checkout the repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: 📜 Setup Poetry
-        uses: abatilo/actions-poetry@3765cf608f2d4a72178a9fc5b918668e542b89b1 # v4.0.0
-
-      - name: 🏗️ Build source and wheel distributions
-        run: |
-          poetry install --with=build
-          poetry build
-          poetry run twine check --strict dist/*
-
-      - name: 🚀 Publish to PyPi
-        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
-        with:
-          attestations: true
-
-      - name: 🚀 Publish to Test-PyPi
-        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
-        with:
-          repository-url: https://test.pypi.org/legacy/
-          attestations: true

.github/workflows/test-doc.yml

@@ -23,18 +23,15 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+      - name: 🐍 Install uv and set Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba # v6.3.1
         with:
           python-version: ${{ matrix.python-version }}
-
-      - name: 📜 Setup Poetry
-        uses: abatilo/actions-poetry@3765cf608f2d4a72178a9fc5b918668e542b89b1 # v4.0.0
+          activate-environment: true
 
       - name: 🏗️ Install dependencies
         run: |
-          poetry install --with=docs
+          uv pip install -r pyproject.toml --group docs
 
       - name: 🧪 Test Docs Build
-        run: |
-          poetry run mkdocs build --verbose
+        run: uv run mkdocs build --verbose

.github/workflows/uv-test.yml

@@ -0,0 +1,35 @@
+name: 🔧 Pytest/Test Workflow
+
+on:
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  run-tests:
+    name: Import Test and Pytest Run
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba # v6.3.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
+
+      - name: 🚀 Install Packages
+        run: uv pip install -r pyproject.toml --group dev --group docs --extra metrics
+
+      - name: 🧪 Run the Import test
+        run: uv run python -c "import supervision; from supervision import assets; from supervision import metrics; print(supervision.__version__)"
+
+      - name: 🧪 Run the Test
+        run: uv run pytest

.pre-commit-config.yaml

@@ -25,14 +25,14 @@ repos:
       - id: mixed-line-ending
 
   -   repo: https://github.com/PyCQA/bandit
-      rev: '1.8.0'
+      rev: '1.8.6'
       hooks:
       -   id: bandit
           args: ["-c", "pyproject.toml"]
           additional_dependencies: ["bandit[toml]"]
 
   -   repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.8.6
+      rev: v0.12.3
       hooks:
       -   id: ruff
           args: [--fix, --exit-non-zero-on-fix]
@@ -48,8 +48,16 @@ repos:
   #       args: ["--number"]
 
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.3.0
+    rev: v2.4.1
     hooks:
       - id: codespell
         additional_dependencies:
           - tomli
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.20.0
+    hooks:
+    -   id: pyupgrade
+        args: ["--py310-plus"]
+        additional_dependencies:
+          - tomli

CONTRIBUTING.md

@@ -155,31 +155,20 @@ Before starting your work on the project, set up your development environment:
     source .venv/bin/activate
     ```
 
-3. Install Poetry:
+3. Install `uv`:
 
-    Using pip:
-
-    ```bash
-    pip install -U pip setuptools
-    pip install poetry
-    ```
-
-    Or using pipx (recommended for global installation):
-
-    ```bash
-    pipx install poetry
-    ```
+    Follow the instructions on the [uv installation page](https://docs.astral.sh/uv/getting-started/installation/).
 
 4. Install project dependencies:
 
     ```bash
-    poetry install
+    uv pip install -r pyproject.toml --extra dev --extra docs --extra metrics
     ```
 
 5. Run pytest to verify the setup:
 
     ```bash
-    poetry run pytest
+    uv run pytest
     ```
 
 ## 🎨 Code Style and Quality
@@ -192,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 --with dev`. 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: `uv pip install -r pyproject.toml --extra 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.
 
@@ -214,7 +203,7 @@ So far, **there is no type checking with mypy**. See [issue](https://github.com/
 
 The `supervision` documentation is stored in a folder called `docs`. The project documentation is built using `mkdocs`.
 
-To run the documentation, install the project requirements with `poetry install --with dev`. Then, run `mkdocs serve` to start the documentation server.
+To run the documentation, install the project requirements with `uv pip install -r pyproject.toml --extra dev --extra docs`. Then, run `mkdocs serve` to start the documentation server.
 
 You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/).
 

README.md

@@ -37,7 +37,7 @@
 ## 💻 install
 
 Pip install the supervision package in a
-[**Python>=3.8**](https://www.python.org/) environment.
+[**Python>=3.9**](https://www.python.org/) environment.
 
 ```bash
 pip install supervision

docs/changelog.md

@@ -1,4 +1,179 @@
-# CHANGELOG
+# Changelog
+
+### 0.26.0 <small>Jul 16, 2025</small>
+
+!!! failure "Removed"
+    `supervision-0.26.0` drops `python3.8` support and upgrade all codes to `python3.9` syntax style.
+
+!!! info "Tip"
+    Supervision’s documentation theme now has a fresh look that is consistent with the documentations of all Roboflow open-source projects. ([#1858](https://github.com/roboflow/supervision/pull/1858))
+
+- Added [#1774](https://github.com/roboflow/supervision/pull/1774): Support for the IOS (Intersection over Smallest) overlap metric that measures how much of the smaller object is covered by the larger one in [`sv.Detections.with_nms`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.with_nms), [`sv.Detections.with_nmm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.with_nmm), [`sv.box_iou_batch`](https://supervision.roboflow.com/0.26.0/detection/utils/iou_and_nms/#supervision.detection.utils.iou_and_nms.box_iou_batch), and [`sv.mask_iou_batch`](https://supervision.roboflow.com/0.26.0/detection/utils/iou_and_nms/#supervision.detection.utils.iou_and_nms.mask_iou_batch).
+
+    ```python
+    import numpy as np
+    import supervision as sv
+
+    boxes_true = np.array([
+        [100, 100, 200, 200],
+        [300, 300, 400, 400]
+    ])
+    boxes_detection = np.array([
+        [150, 150, 250, 250],
+        [320, 320, 420, 420]
+    ])
+
+    sv.box_iou_batch(
+        boxes_true=boxes_true,
+        boxes_detection=boxes_detection,
+        overlap_metric=sv.OverlapMetric.IOU
+    )
+
+    # array([[0.14285714, 0.        ],
+    #        [0.        , 0.47058824]])
+
+    sv.box_iou_batch(
+        boxes_true=boxes_true,
+        boxes_detection=boxes_detection,
+        overlap_metric=sv.OverlapMetric.IOS
+    )
+
+    # array([[0.25, 0.  ],
+    #        [0.  , 0.64]])
+    ```
+
+- Added [#1874](https://github.com/roboflow/supervision/pull/1874): [`sv.box_iou`](https://supervision.roboflow.com/0.26.0/detection/utils/iou_and_nms/#supervision.detection.utils.iou_and_nms.box_iou) that efficiently computes the Intersection over Union (IoU) between two individual bounding boxes.
+
+- Added [#1816](https://github.com/roboflow/supervision/pull/1816): Support for frame limitations and progress bar in [`sv.process_video`](https://supervision.roboflow.com/0.26.0/utils/video/#supervision.utils.video.process_video).
+
+- Added [#1788](https://github.com/roboflow/supervision/pull/1788): Support for creating [`sv.KeyPoints`](https://supervision.roboflow.com/0.26.0/keypoint/core/#supervision.keypoint.core.KeyPoints) objects from [ViTPose](https://huggingface.co/docs/transformers/en/model_doc/vitpose) and [ViTPose++](https://huggingface.co/docs/transformers/en/model_doc/vitpose#vitpose-models) inference results via [`sv.KeyPoints.from_transformers`](https://supervision.roboflow.com/0.26.0/keypoint/core/#supervision.keypoint.core.KeyPoints.from_transformers).
+
+- Added [#1823](https://github.com/roboflow/supervision/pull/1823): [`sv.xyxy_to_xcycarh`](https://supervision.roboflow.com/0.26.0/detection/utils/converters/#supervision.detection.utils.converters.xyxy_to_xcycarh) function to convert bounding box coordinates from `(x_min, y_min, x_max, y_max)` into measurement space to format `(center x, center y, aspect ratio, height)`, where the aspect ratio is `width / height`.
+
+- Added [#1788](https://github.com/roboflow/supervision/pull/1788): [`sv.xyxy_to_xywh`](https://supervision.roboflow.com/0.26.0/detection/utils/converters/#supervision.detection.utils.converters.xyxy_to_xywh) function to convert bounding box coordinates from `(x_min, y_min, x_max, y_max)` format to `(x, y, width, height)` format.
+
+- Changed [#1820](https://github.com/roboflow/supervision/pull/1820): [`sv.LabelAnnotator`](https://supervision.roboflow.com/0.26.0/detection/annotators/#supervision.annotators.core.LabelAnnotator) now supports the `smart_position` parameter to automatically keep labels within frame boundaries, and the `max_line_length` parameter to control text wrapping for long or multi-line labels.
+
+- Changed [#1825](https://github.com/roboflow/supervision/pull/1825): [`sv.LabelAnnotator`](https://supervision.roboflow.com/0.26.0/detection/annotators/#supervision.annotators.core.LabelAnnotator) now supports non-string labels.
+
+- Changed [#1792](https://github.com/roboflow/supervision/pull/1792): [`sv.Detections.from_vlm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.from_vlm) now supports parsing bounding boxes and segmentation masks from responses generated by [Google Gemini models](https://ai.google.dev/gemini-api/docs/vision).
+
+    ```python
+    import supervision as sv
+
+    gemini_response_text = """```json
+        [
+            {"box_2d": [543, 40, 728, 200], "label": "cat", "id": 1},
+            {"box_2d": [653, 352, 820, 522], "label": "dog", "id": 2}
+        ]
+    ```"""
+
+    detections = sv.Detections.from_vlm(
+        sv.VLM.GOOGLE_GEMINI_2_5,
+        gemini_response_text,
+        resolution_wh=(1000, 1000),
+        classes=['cat', 'dog'],
+    )
+
+    detections.xyxy
+    # array([[543., 40., 728., 200.], [653., 352., 820., 522.]])
+
+    detections.data
+    # {'class_name': array(['cat', 'dog'], dtype='<U26')}
+
+    detections.class_id
+    # array([0, 1])
+    ```
+
+- Changed [#1878](https://github.com/roboflow/supervision/pull/1878): [`sv.Detections.from_vlm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.from_vlm) now supports parsing bounding boxes from responses generated by [Moondream](https://github.com/vikhyat/moondream).
+
+    ```python
+    import supervision as sv
+
+    moondream_result = {
+        'objects': [
+            {
+                'x_min': 0.5704046934843063,
+                'y_min': 0.20069346576929092,
+                'x_max': 0.7049859315156937,
+                'y_max': 0.3012596592307091
+            },
+            {
+                'x_min': 0.6210969910025597,
+                'y_min': 0.3300672620534897,
+                'x_max': 0.8417936339974403,
+                'y_max': 0.4961046129465103
+            }
+        ]
+    }
+
+    detections = sv.Detections.from_vlm(
+        sv.VLM.MOONDREAM,
+        moondream_result,
+        resolution_wh=(1000, 1000),
+    )
+
+    detections.xyxy
+    # array([[1752.28,  818.82, 2165.72, 1229.14],
+    #        [1908.01, 1346.67, 2585.99, 2024.11]])
+    ```
+
+- Changed [#1709](https://github.com/roboflow/supervision/pull/1790): [`sv.Detections.from_vlm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.from_vlm) now supports parsing bounding boxes from responses generated by [Qwen-2.5 VL](https://github.com/QwenLM/Qwen2.5-VL).
+
+    ```python
+    import supervision as sv
+
+    qwen_2_5_vl_result = """```json
+    [
+        {"bbox_2d": [139, 768, 315, 954], "label": "cat"},
+        {"bbox_2d": [366, 679, 536, 849], "label": "dog"}
+    ]
+    ```"""
+
+    detections = sv.Detections.from_vlm(
+        sv.VLM.QWEN_2_5_VL,
+        qwen_2_5_vl_result,
+        input_wh=(1000, 1000),
+        resolution_wh=(1000, 1000),
+        classes=['cat', 'dog'],
+    )
+
+    detections.xyxy
+    # array([[139., 768., 315., 954.], [366., 679., 536., 849.]])
+
+    detections.class_id
+    # array([0, 1])
+
+    detections.data
+    # {'class_name': array(['cat', 'dog'], dtype='<U10')}
+
+    detections.class_id
+    # array([0, 1])
+    ```
+
+- Changed [#1786](https://github.com/roboflow/supervision/pull/1786): Significantly improved the speed of HSV color mapping in [`sv.HeatMapAnnotator`](https://supervision.roboflow.com/0.26.0/detection/annotators/#supervision.annotators.core.HeatMapAnnotator), achieving approximately 28x faster performance on 1920x1080 frames.
+
+- Fix [#1834](https://github.com/roboflow/supervision/pull/1834): Supervision’s [`sv.MeanAveragePrecision`](https://supervision.roboflow.com/0.26.0/metrics/mean_average_precision/#supervision.metrics.mean_average_precision.MeanAveragePrecision) is now fully aligned with [pycocotools](https://github.com/ppwwyyxx/cocoapi), the official COCO evaluation tool, ensuring accurate and standardized metrics. This update enabled us to launch a new version of the [Computer Vision Model Leaderboard](https://leaderboard.roboflow.com/).
+
+    ```python
+    import supervision as sv
+    from supervision.metrics import MeanAveragePrecision
+
+    predictions = sv.Detections(...)
+    targets = sv.Detections(...)
+
+    map_metric = MeanAveragePrecision()
+    map_metric.update(predictions, targets).compute()
+
+    # Average Precision (AP) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.464
+    # Average Precision (AP) @[ IoU=0.50      | area=   all | maxDets=100 ] = 0.637
+    # Average Precision (AP) @[ IoU=0.75      | area=   all | maxDets=100 ] = 0.203
+    # Average Precision (AP) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.284
+    # Average Precision (AP) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.497
+    # Average Precision (AP) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.629
+    ```
+
+- Fix [#1767](https://github.com/roboflow/supervision/pull/1767): Fixed losing `sv.Detections.data` when detections filtering.
 
 ### 0.25.0 <small>Nov 12, 2024</small>
 

docs/deprecated.md

@@ -7,21 +7,19 @@ 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.
 
-- 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`](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.
+- `sv.LMM` enum is deprecated and will be removed in `supervision-0.31.0`. Use `sv.VLM` instead.
+- [`sv.Detections.from_lmm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.from_lmm) property is deprecated and will be removed in `supervision-0.31.0`. Use [`sv.Detections.from_vlm`](https://supervision.roboflow.com/0.26.0/detection/core/#supervision.detection.core.Detections.from_vlm) instead.
 
 # Removed
 
-### 0.25.0
+### 0.26.0
+
+- The `sv.DetectionDataset.images` property has been 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. Also, constructing `sv.DetectionDataset` with parameter `images` as `Dict[str, np.ndarray]` is deprecated and has been removed in `supervision-0.26.0`. Please pass a list of paths `List[str]` instead.
+- The name `sv.BoundingBoxAnnotator` is deprecated and has been removed in `supervision-0.26.0`. It has been renamed to [`sv.BoxAnnotator`](https://supervision.roboflow.com/0.22.0/detection/annotators/#supervision.annotators.core.BoxAnnotator).
 
-No removals in this version!
 
 ### 0.24.0
 
@@ -35,12 +33,12 @@ No removals in this version!
 
 ### 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()` 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__` was removed as of `supervision-0.22.0`. Use the attribute [`FPSMonitor.fps`](utils/video.md/#supervision.utils.video.FPSMonitor.fps) instead.
+- `sv.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 `sv.Color.white()` was removed as of `supervision-0.22.0`. Use the constant `sv.Color.WHITE` instead.
+- The method `sv.Color.black()` was removed as of `supervision-0.22.0`. Use the constant `sv.Color.BLACK` instead.
+- The method `sv.Color.red()` was removed as of `supervision-0.22.0`. Use the constant `sv.Color.RED` instead.
+- The method `sv.Color.green()` was removed as of `supervision-0.22.0`. Use the constant `sv.Color.GREEN` instead.
+- The method `sv.Color.blue()` was removed as of `supervision-0.22.0`. Use the constant `sv.Color.BLUE` instead.
+- The method `sv.ColorPalette.default()` was removed as of `supervision-0.22.0`. Use the constant [`ColorPalette.DEFAULT`](/utils/draw/#supervision.draw.color.ColorPalette.DEFAULT) instead.
+- `sv.BoxAnnotator` was removed as of `supervision-0.22.0`, however `sv.BoundingBoxAnnotator` was immediately renamed to `sv.BoxAnnotator`. Use [`BoxAnnotator`](detection/annotators.md/#supervision.annotators.core.BoxAnnotator) and [`LabelAnnotator`](detection/annotators.md/#supervision.annotators.core.LabelAnnotator) instead of the old `sv.BoxAnnotator`.
+- The method `sv.FPSMonitor.__call__` was removed as of `supervision-0.22.0`. Use the attribute [`sv.FPSMonitor.fps`](utils/video.md/#supervision.utils.video.FPSMonitor.fps) instead.

docs/detection/annotators.md

@@ -28,28 +28,26 @@ Annotators accept detections and apply box or mask visualizations to the detecti
 
     </div>
 
-    <!--
-    === "RoundBox"
+=== "RoundBox"
 
-        ```python
-        import supervision as sv
+    ```python
+    import supervision as sv
 
-        image = ...
-        detections = sv.Detections(...)
+    image = ...
+    detections = sv.Detections(...)
 
-        round_box_annotator = sv.RoundBoxAnnotator()
-        annotated_frame = round_box_annotator.annotate(
-            scene=image.copy(),
-            detections=detections
-        )
-        ```
+    round_box_annotator = sv.RoundBoxAnnotator()
+    annotated_frame = round_box_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
+    ```
 
-        <div class="result" markdown>
+    <div class="result" markdown>
 
-        ![round-box-annotator-example](https://media.roboflow.com/supervision-annotator-examples/round-box-annotator-example-purple.png){ align=center width="800" }
+    ![round-box-annotator-example](https://media.roboflow.com/supervision-annotator-examples/round-box-annotator-example-purple.png){ align=center width="800" }
 
-        </div>
-    -->
+    </div>
 
 === "BoxCorner"
 

docs/detection/double_detection_filter.md

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

docs/detection/tools/line_zone.md

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

docs/detection/utils.md

@@ -1,108 +0,0 @@
----
-comments: true
-status: new
----
-
-# Detection Utils
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.box_iou_batch">box_iou_batch</a></h2>
-</div>
-
-:::supervision.detection.utils.box_iou_batch
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.mask_iou_batch">mask_iou_batch</a></h2>
-</div>
-
-:::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>
-
-:::supervision.detection.utils.polygon_to_mask
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.mask_to_xyxy">mask_to_xyxy</a></h2>
-</div>
-
-:::supervision.detection.utils.mask_to_xyxy
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.mask_to_polygons">mask_to_polygons</a></h2>
-</div>
-
-:::supervision.detection.utils.mask_to_polygons
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.polygon_to_xyxy">polygon_to_xyxy</a></h2>
-</div>
-
-:::supervision.detection.utils.polygon_to_xyxy
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.filter_polygons_by_area">filter_polygons_by_area</a></h2>
-</div>
-
-:::supervision.detection.utils.filter_polygons_by_area
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.move_boxes">move_boxes</a></h2>
-</div>
-
-:::supervision.detection.utils.move_boxes
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.move_masks">move_masks</a></h2>
-</div>
-
-:::supervision.detection.utils.move_masks
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.scale_boxes">scale_boxes</a></h2>
-</div>
-
-:::supervision.detection.utils.scale_boxes
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.clip_boxes">clip_boxes</a></h2>
-</div>
-
-:::supervision.detection.utils.clip_boxes
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.pad_boxes">pad_boxes</a></h2>
-</div>
-
-:::supervision.detection.utils.pad_boxes
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.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.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.contains_holes">contains_holes</a></h2>
-</div>
-
-:::supervision.detection.utils.contains_holes
-
-<div class="md-typeset">
-  <h2><a href="#supervision.detection.utils.contains_multiple_segments">contains_multiple_segments</a></h2>
-</div>
-
-:::supervision.detection.utils.contains_multiple_segments

docs/detection/utils/boxes.md

@@ -0,0 +1,36 @@
+---
+comments: true
+status: new
+---
+
+# Boxes Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.boxes.move_boxes">move_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.boxes.move_boxes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.boxes.scale_boxes">scale_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.boxes.scale_boxes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.boxes.utils.clip_boxes">clip_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.boxes.clip_boxes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.boxes.pad_boxes">pad_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.boxes.pad_boxes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.boxes.denormalize_boxes">denormalize_boxes</a></h2>
+</div>
+
+:::supervision.detection.utils.boxes.denormalize_boxes

docs/detection/utils/converters.md

@@ -0,0 +1,60 @@
+---
+comments: true
+status: new
+---
+
+# Converters Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.xyxy_to_xywh">xyxy_to_xywh</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.xyxy_to_xywh
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.xywh_to_xyxy">xywh_to_xyxy</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.xywh_to_xyxy
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.xyxy_to_xcycarh">xyxy_to_xcycarh</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.xyxy_to_xcycarh
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.xcycwh_to_xyxy">xcycwh_to_xyxy</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.xcycwh_to_xyxy
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.xyxy_to_polygons">xyxy_to_polygons</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.xyxy_to_polygons
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.mask_to_xyxy">mask_to_xyxy</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.mask_to_xyxy
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.mask_to_polygons">mask_to_polygons</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.mask_to_polygons
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.polygon_to_mask">polygon_to_mask</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.polygon_to_mask
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.converters.polygon_to_xyxy">polygon_to_xyxy</a></h2>
+</div>
+
+:::supervision.detection.utils.converters.polygon_to_xyxy

docs/detection/utils/iou_and_nms.md

@@ -0,0 +1,72 @@
+---
+comments: true
+status: new
+---
+
+# IoU and NMS Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.OverlapFilter">OverlapFilter</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.OverlapFilter
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.OverlapMetric">OverlapMetric</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.OverlapMetric
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.utils.box_iou">box_iou</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.box_iou
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.box_iou_batch">box_iou_batch</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.box_iou_batch
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.box_iou_batch_with_jaccard">box_iou_batch_with_jaccard</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.box_iou_batch_with_jaccard
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.mask_iou_batch">mask_iou_batch</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.mask_iou_batch
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.oriented_box_iou_batch">oriented_box_iou_batch</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.oriented_box_iou_batch
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.box_non_max_suppression">box_non_max_suppression</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.box_non_max_suppression
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.mask_non_max_suppression">mask_non_max_suppression</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.mask_non_max_suppression
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.box_non_max_merge">box_non_max_merge</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.box_non_max_merge
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.iou_and_nms.mask_non_max_merge">mask_non_max_merge</a></h2>
+</div>
+
+:::supervision.detection.utils.iou_and_nms.mask_non_max_merge

docs/detection/utils/masks.md

@@ -0,0 +1,24 @@
+---
+comments: true
+status: new
+---
+
+# Masks Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.masks.move_masks">move_masks</a></h2>
+</div>
+
+:::supervision.detection.utils.masks.move_masks
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.masks.contains_holes">contains_holes</a></h2>
+</div>
+
+:::supervision.detection.utils.masks.contains_holes
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.masks.contains_multiple_segments">contains_multiple_segments</a></h2>
+</div>
+
+:::supervision.detection.utils.masks.contains_multiple_segments

docs/detection/utils/polygons.md

@@ -0,0 +1,18 @@
+---
+comments: true
+status: new
+---
+
+# Polygons Utils
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.polygons.filter_polygons_by_area">filter_polygons_by_area</a></h2>
+</div>
+
+:::supervision.detection.utils.polygons.filter_polygons_by_area
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.polygons.approximate_polygon">approximate_polygon</a></h2>
+</div>
+
+:::supervision.detection.utils.polygons.approximate_polygon

docs/how_to/track_objects.md

@@ -55,7 +55,7 @@ it will be modified to include tracking, labeling, and trace annotations.
     from ultralytics import YOLO
 
     model = YOLO("yolov8n.pt")
-    box_annotator = sv.BoundingBoxAnnotator()
+    box_annotator = sv.BoxAnnotator()
 
     def callback(frame: np.ndarray, _: int) -> np.ndarray:
         results = model(frame)[0]
@@ -77,7 +77,7 @@ it will be modified to include tracking, labeling, and trace annotations.
     from inference.models.utils import get_roboflow_model
 
     model = get_roboflow_model(model_id="yolov8n-640", api_key=<ROBOFLOW API KEY>)
-    box_annotator = sv.BoundingBoxAnnotator()
+    box_annotator = sv.BoxAnnotator()
 
     def callback(frame: np.ndarray, _: int) -> np.ndarray:
         results = model.infer(frame)[0]
@@ -112,7 +112,7 @@ enabling the continuous following of the object's motion path across different f
 
     model = YOLO("yolov8n.pt")
     tracker = sv.ByteTrack()
-    box_annotator = sv.BoundingBoxAnnotator()
+    box_annotator = sv.BoxAnnotator()
 
     def callback(frame: np.ndarray, _: int) -> np.ndarray:
         results = model(frame)[0]
@@ -136,7 +136,7 @@ enabling the continuous following of the object's motion path across different f
 
     model = get_roboflow_model(model_id="yolov8n-640", api_key=<ROBOFLOW API KEY>)
     tracker = sv.ByteTrack()
-    box_annotator = sv.BoundingBoxAnnotator()
+    box_annotator = sv.BoxAnnotator()
 
     def callback(frame: np.ndarray, _: int) -> np.ndarray:
         results = model.infer(frame)[0]
@@ -168,7 +168,7 @@ offering a clear visual representation of each object's class and unique identif
 
     model = YOLO("yolov8n.pt")
     tracker = sv.ByteTrack()
-    box_annotator = sv.BoundingBoxAnnotator()
+    box_annotator = sv.BoxAnnotator()
     label_annotator = sv.LabelAnnotator()
 
     def callback(frame: np.ndarray, _: int) -> np.ndarray:
@@ -177,9 +177,9 @@ offering a clear visual representation of each object's class and unique identif
         detections = tracker.update_with_detections(detections)
 
         labels = [
-            f"#{tracker_id} {results.names[class_id]}"
-            for class_id, tracker_id
-            in zip(detections.class_id, detections.tracker_id)
+            f"#{tracker_id} {class_name}"
+            for class_name, tracker_id
+            in zip(detections.data["class_name"], detections.tracker_id)
         ]
 
         annotated_frame = box_annotator.annotate(
@@ -203,7 +203,7 @@ offering a clear visual representation of each object's class and unique identif
 
     model = get_roboflow_model(model_id="yolov8n-640", api_key=<ROBOFLOW API KEY>)
     tracker = sv.ByteTrack()
-    box_annotator = sv.BoundingBoxAnnotator()
+    box_annotator = sv.BoxAnnotator()
     label_annotator = sv.LabelAnnotator()
 
     def callback(frame: np.ndarray, _: int) -> np.ndarray:
@@ -212,9 +212,9 @@ offering a clear visual representation of each object's class and unique identif
         detections = tracker.update_with_detections(detections)
 
         labels = [
-            f"#{tracker_id} {results.names[class_id]}"
-            for class_id, tracker_id
-            in zip(detections.class_id, detections.tracker_id)
+            f"#{tracker_id} {class_name}"
+            for class_name, tracker_id
+            in zip(detections.data["class_name"], detections.tracker_id)
         ]
 
         annotated_frame = box_annotator.annotate(
@@ -250,7 +250,7 @@ movement patterns and interactions between objects in the video.
 
     model = YOLO("yolov8n.pt")
     tracker = sv.ByteTrack()
-    box_annotator = sv.BoundingBoxAnnotator()
+    box_annotator = sv.BoxAnnotator()
     label_annotator = sv.LabelAnnotator()
     trace_annotator = sv.TraceAnnotator()
 
@@ -260,9 +260,9 @@ movement patterns and interactions between objects in the video.
         detections = tracker.update_with_detections(detections)
 
         labels = [
-            f"#{tracker_id} {results.names[class_id]}"
-            for class_id, tracker_id
-            in zip(detections.class_id, detections.tracker_id)
+            f"#{tracker_id} {class_name}"
+            for class_name, tracker_id
+            in zip(detections.data["class_name"], detections.tracker_id)
         ]
 
         annotated_frame = box_annotator.annotate(
@@ -288,7 +288,7 @@ movement patterns and interactions between objects in the video.
 
     model = get_roboflow_model(model_id="yolov8n-640", api_key=<ROBOFLOW API KEY>)
     tracker = sv.ByteTrack()
-    box_annotator = sv.BoundingBoxAnnotator()
+    box_annotator = sv.BoxAnnotator()
     label_annotator = sv.LabelAnnotator()
     trace_annotator = sv.TraceAnnotator()
 
@@ -298,9 +298,9 @@ movement patterns and interactions between objects in the video.
         detections = tracker.update_with_detections(detections)
 
         labels = [
-            f"#{tracker_id} {results.names[class_id]}"
-            for class_id, tracker_id
-            in zip(detections.class_id, detections.tracker_id)
+            f"#{tracker_id} {class_name}"
+            for class_name, tracker_id
+            in zip(detections.data["class_name"], detections.tracker_id)
         ]
 
         annotated_frame = box_annotator.annotate(

docs/index.md

@@ -10,13 +10,19 @@ hide:
   <h1></h1>
 </div>
 
-<div align="center" id="logo">
+<div align="center" id="logo" style="padding-top: 1rem;">
   <a align="center" href="" target="_blank">
       <img width="850"
           src="https://media.roboflow.com/open-source/supervision/rf-supervision-banner.png?updatedAt=1678995927529">
   </a>
 </div>
 
+<style>
+    #hello {
+        margin: 0;
+    }
+</style>
+
 ## 👋 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!
@@ -31,7 +37,7 @@ We write your reusable computer vision tools. Whether you need to load your data
 ## 💻 Install
 
 You can install `supervision` in a
-[**Python>=3.8**](https://www.python.org/) environment.
+[**Python>=3.9**](https://www.python.org/) environment.
 
 !!! example "Installation"
 
@@ -113,18 +119,19 @@ You can install `supervision` in a
         pip install -e "."
         ```
 
-    === "poetry"
+    === "uv"
         ```bash
         # clone repository and navigate to root directory
         git clone --depth 1 -b develop https://github.com/roboflow/supervision.git
         cd supervision
 
         # setup python environment and activate it
-        poetry env use python3.10
-        poetry shell
+        uv venv
+        source .venv/bin/activate
 
         # installation
-        poetry install
+        uv pip install -r pyproject.toml -e . --all-extras
+
         ```
 
 ## 🚀 Quickstart

docs/javascripts/cookbooks-card.js

@@ -59,7 +59,7 @@ document.addEventListener("DOMContentLoaded", function () {
             <div
                 class="author-container"
                 data-login="${authorData.login}-${elementIndex}"
-                style="margin-left: ${marginLeft}; z-index: ${zIndex};"
+                style="margin-left: ${marginLeft};"
             >
                 <a
                     href="https://github.com/${authorData.login}"
@@ -90,14 +90,17 @@ document.addEventListener("DOMContentLoaded", function () {
         ).join(',&nbsp;');
 
         let authorsHTML = `
-        <div class="authors">
+        <div class="authors" style="margin: 0;">
             ${authorAvatarsHTML}
             <div class="author-names">${authorNamesHTML}</div>
         </div>
         `;
 
         element.innerText = `
-            <div style="flex-direction: column; height: 100%; display: flex;
+            <div style="
+                display: grid !important;
+                grid-template-rows: auto;
+                height: 100%;
             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};">
@@ -105,13 +108,14 @@ document.addEventListener("DOMContentLoaded", function () {
                 </span>
             </div>
             ${authorsHTML}
-            <div style="font-size: 12px; color: ${theme.color}; display: flex; flex: 0; justify-content: space-between">
+            <div style="font-size: 12px; color: ${theme.color}; display: grid; grid-template-columns: auto 3fr; justify-content: space-between; gap: 1rem;">
                 <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">
+                <div style="display: flex; align-items: center; flex-wrap: wrap; align-content: right;
+  gap: 0.1rem;">
                 ${labelHTML}
                 </div>
             </div>

docs/javascripts/mathjax.js

@@ -0,0 +1,19 @@
+window.MathJax = {
+    tex: {
+      inlineMath: [["\\(", "\\)"]],
+      displayMath: [["\\[", "\\]"]],
+      processEscapes: true,
+      processEnvironments: true
+    },
+    options: {
+      ignoreHtmlClass: ".*|",
+      processHtmlClass: "arithmatex"
+    }
+  };
+
+  document$.subscribe(() => {
+    MathJax.startup.output.clearCache()
+    MathJax.typesetClear()
+    MathJax.texReset()
+    MathJax.typesetPromise()
+  })

docs/javascripts/segment.js

@@ -0,0 +1,4 @@
+!function(){var i="analytics",analytics=window[i]=window[i]||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","screen","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware","register"];analytics.factory=function(e){return function(){if(window[i].initialized)return window[i][e].apply(window[i],arguments);var n=Array.prototype.slice.call(arguments);if(["track","screen","alias","group","page","identify"].indexOf(e)>-1){var c=document.querySelector("link[rel='canonical']");n.push({__t:"bpc",c:c&&c.getAttribute("href")||void 0,p:location.pathname,u:location.href,s:location.search,t:document.title,r:document.referrer})}n.unshift(e);analytics.push(n);return analytics}};for(var n=0;n<analytics.methods.length;n++){var key=analytics.methods[n];analytics[key]=analytics.factory(key)}analytics.load=function(key,n){var t=document.createElement("script");t.type="text/javascript";t.async=!0;t.setAttribute("data-global-segment-analytics-key",i);t.src="https://cdn.segment.com/analytics.js/v1/" + key + "/analytics.min.js";var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(t,r);analytics._loadOptions=n};analytics._writeKey="rMvrPeZBJYyOPJSGCNhMlnTJb8VhFiWU";;analytics.SNIPPET_VERSION="5.2.0";
+  analytics.load("eohFog7VZiAhGJGEr5Sh7BM1mFKmUvDC");
+  document$.subscribe(analytics.page);
+  }}();

docs/keypoint/annotators.md

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

docs/metrics/common_values.md

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

docs/metrics/f1_score.md

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

docs/metrics/mean_average_precision.md

@@ -16,3 +16,9 @@ status: new
 </div>
 
 :::supervision.metrics.mean_average_precision.MeanAveragePrecisionResult
+
+<div class="md-typeset">
+    <h2><a href="#supervision.dataset.formats.coco.get_coco_class_index_mapping">get_coco_class_index_mapping</a></h2>
+</div>
+
+:::supervision.dataset.formats.coco.get_coco_class_index_mapping

docs/metrics/mean_average_recall.md

@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---
 
 # Mean Average Recall

docs/metrics/precision.md

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

docs/metrics/recall.md

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

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

@@ -93,7 +93,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q inference-gpu \"supervision[assets]\""
+                "!pip install -q inference-gpu \"supervision\""
             ]
         },
         {
@@ -156,7 +156,7 @@
         },
         {
             "cell_type": "code",
-            "execution_count": 4,
+            "execution_count": null,
             "metadata": {
                 "colab": {
                     "base_uri": "https://localhost:8080/"
@@ -207,7 +207,6 @@
             ],
             "source": [
                 "import supervision as sv\n",
-                "from supervision.assets import download_assets, VideoAssets\n",
                 "from inference.models.utils import get_roboflow_model\n",
                 "\n",
                 "\n",

docs/notebooks/download-supervision-assets.ipynb

@@ -17,7 +17,7 @@
         },
         {
             "cell_type": "code",
-            "execution_count": 10,
+            "execution_count": null,
             "metadata": {
                 "vscode": {
                     "languageId": "shellscript"
@@ -25,7 +25,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q \"supervision[assets]\""
+                "pip install -q \"supervision\""
             ]
         },
         {

docs/notebooks/evaluating-alignment-of-text-to-image-diffusion-models.ipynb

@@ -101,7 +101,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q torch diffusers accelerate inference-gpu[yolo-world] dill git+https://github.com/openai/CLIP.git supervision==0.19.0rc5"
+                "!pip install -q torch diffusers accelerate inference-gpu[yolo-world] dill git+https://github.com/openai/CLIP.git supervision"
             ]
         },
         {

docs/notebooks/object-tracking.ipynb

@@ -92,7 +92,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q inference-gpu \"supervision[assets]\""
+                "!pip install -q inference-gpu \"supervision\""
             ]
         },
         {

docs/notebooks/occupancy_analytics.ipynb

@@ -72,7 +72,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install roboflow supervision==0.19.0 -q"
+                "!pip install roboflow supervision -q"
             ]
         },
         {

docs/notebooks/quickstart.ipynb

@@ -300,7 +300,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q \"ultralytics<=8.3.40\""
+                "!pip install -q ultralytics"
             ]
         },
         {
@@ -495,7 +495,7 @@
             "source": [
                 "from ultralytics import YOLO\n",
                 "\n",
-                "model = YOLO(\"yolov8x.pt\")\n",
+                "model = YOLO(\"yolo11x.pt\")\n",
                 "result = model(image, verbose=False)[0]\n",
                 "detections = sv.Detections.from_ultralytics(result)"
             ]
@@ -594,7 +594,7 @@
         },
         {
             "cell_type": "code",
-            "execution_count": 33,
+            "execution_count": null,
             "metadata": {
                 "id": "yM6dmicTRGl6"
             },
@@ -602,7 +602,7 @@
             "source": [
                 "from ultralytics import YOLO\n",
                 "\n",
-                "model = YOLO(\"yolov8x-seg.pt\")\n",
+                "model = YOLO(\"yolo11x-seg.pt\")\n",
                 "result = model(image, verbose=False)[0]\n",
                 "detections = sv.Detections.from_ultralytics(result)"
             ]
@@ -926,7 +926,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q supervision[assets]"
+                "!pip install -q supervision"
             ]
         },
         {

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

@@ -32,7 +32,7 @@
             },
             "outputs": [],
             "source": [
-                "!pip install -q inference requests tqdm supervision==0.21.0"
+                "!pip install -q inference requests tqdm supervision"
             ]
         },
         {
@@ -695,12 +695,12 @@
             "source": [
                 "###\u00a0Annotate Image with Detections\n",
                 "\n",
-                "Finally, we can annotate the image with the predictions. Since we are working with an object detection model, we will use the [`sv.BoundingBoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoundingBoxAnnotator) and [`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/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`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) and [`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator) classes."
             ]
         },
         {
             "cell_type": "code",
-            "execution_count": 49,
+            "execution_count": null,
             "metadata": {
                 "colab": {
                     "base_uri": "https://localhost:8080/",
@@ -722,7 +722,7 @@
                 }
             ],
             "source": [
-                "bounding_box_annotator = sv.BoundingBoxAnnotator()\n",
+                "bounding_box_annotator = sv.BoxAnnotator()\n",
                 "label_annotator = sv.LabelAnnotator()\n",
                 "\n",
                 "annotated_frame = frame.copy()\n",

docs/stylesheets/cookbooks-card.css

@@ -15,7 +15,7 @@
 /* Large screens (1024px and up) */
 @media (min-width: 1024px) {
     .custom-grid {
-        grid-template-columns: repeat(3, minmax(0, 1fr));
+        grid-template-columns: repeat(4, minmax(0, 1fr));
     }
 }
 

docs/stylesheets/extra.css

@@ -1,7 +1,10 @@
-:root {
+:root, body {
   /* Default to light theme */
   --md-primary-fg-color:        #8315F9;
-  --md-accent-fg-color:         #00FFCE;
+  --md-code-hl-color:          #8315F9 !important;
+  --md-accent-fg-color:        #8315F9 !important;
+  --md-code-hl-color--light: #e8d2ff89 !important;
+  --md-footer-fg-color--light: rgb(111, 108, 121) !important;
 }
 
 body.light {
@@ -9,6 +12,202 @@ body.light {
   --md-text-color:              #000000;
   --md-h2-color:                #000000;
 }
+.md-grid {
+  max-width: 85%;
+  margin: auto;
+}
+.sublist {
+  display: none;
+  list-style: none;
+  padding-left: 0;
+  background: white;
+  position: absolute;
+  border-radius: 8px;
+  margin-top: 0.25rem;
+}
+.sublist {
+  transition: opacity 0.5s ease-in-out;
+  display: none;
+  position: absolute; /* Ensure it overlaps and doesn't break flow */
+  background: white;  /* So it's visible */
+  z-index: 1000;
+}
+.sublist li {
+  padding: 0.5rem;
+}
+#products-list *:hover .products-sublist {
+  display: block;
+}
+#resources-list *, #products-list * {
+  cursor: pointer;
+}
+.products-sublist, .resources-sublist {
+  padding: 0.25rem;
+}
+.products-sublist li:hover, .resources-sublist li:hover, .md-nav__link[href]:hover {
+  background: rgb(242, 241, 247) !important;
+  border-radius: 6px;
+  color: initial !important;
+}
+.md-search {
+  flex-grow: 2;
+}
+.portfolio-section .md-grid {
+  max-width: 100%;
+}
+.md-header__inner {
+  align-items: center;
+  display: grid;
+  grid-template-columns: 0.1fr 1.4fr 2fr 2fr;
+  padding-right: 1rem;
+}
+.md-search__inner {
+  max-width: 600px;
+  width: 100%;
+  min-width: 100%;
+}
+.md-search__input {
+  background: white;
+  border: 1px solid rgb(229, 231, 235);
+  border-radius: 8px;
+  color: rgb(111, 108, 121);
+}
+.md-search__form *, .md-search__icon, .md-search__input {
+  color: rgb(111, 108, 121);
+}
+.md-search__input::placeholder {
+  color: rgb(156, 163, 175);
+}
+.md-search__form {
+  background: none !important;
+}
+.md-footer, .md-footer-meta {
+  background-color: transparent;
+  color: rgb(111, 108, 121);
+}
+.md-typeset .tabbed-set > input:first-child:checked ~ .tabbed-labels > :first-child, .md-typeset .tabbed-set > input:nth-child(10):checked ~ .tabbed-labels > :nth-child(10), .md-typeset .tabbed-set > input:nth-child(11):checked ~ .tabbed-labels > :nth-child(11), .md-typeset .tabbed-set > input:nth-child(12):checked ~ .tabbed-labels > :nth-child(12), .md-typeset .tabbed-set > input:nth-child(13):checked ~ .tabbed-labels > :nth-child(13), .md-typeset .tabbed-set > input:nth-child(14):checked ~ .tabbed-labels > :nth-child(14), .md-typeset .tabbed-set > input:nth-child(15):checked ~ .tabbed-labels > :nth-child(15), .md-typeset .tabbed-set > input:nth-child(16):checked ~ .tabbed-labels > :nth-child(16), .md-typeset .tabbed-set > input:nth-child(17):checked ~ .tabbed-labels > :nth-child(17), .md-typeset .tabbed-set > input:nth-child(18):checked ~ .tabbed-labels > :nth-child(18), .md-typeset .tabbed-set > input:nth-child(19):checked ~ .tabbed-labels > :nth-child(19), .md-typeset .tabbed-set > input:nth-child(2):checked ~ .tabbed-labels > :nth-child(2), .md-typeset .tabbed-set > input:nth-child(20):checked ~ .tabbed-labels > :nth-child(20), .md-typeset .tabbed-set > input:nth-child(3):checked ~ .tabbed-labels > :nth-child(3), .md-typeset .tabbed-set > input:nth-child(4):checked ~ .tabbed-labels > :nth-child(4), .md-typeset .tabbed-set > input:nth-child(5):checked ~ .tabbed-labels > :nth-child(5), .md-typeset .tabbed-set > input:nth-child(6):checked ~ .tabbed-labels > :nth-child(6), .md-typeset .tabbed-set > input:nth-child(7):checked ~ .tabbed-labels > :nth-child(7), .md-typeset .tabbed-set > input:nth-child(8):checked ~ .tabbed-labels > :nth-child(8), .md-typeset .tabbed-set > input:nth-child(9):checked ~ .tabbed-labels > :nth-child(9) {
+  color: #8315F9;
+  border-bottom: 1px solid #8315F9;
+}
+.md-footer *, html .md-footer-meta.md-typeset a {
+  color: rgb(111, 108, 121);
+}
+.repo-card {
+  height: 100%;
+}
+.header-btn {
+  text-align: center;
+}
+.header-btn, .sublist {
+  box-shadow: rgb(255, 255, 255) 0px 0px 0px 0px, rgb(217, 215, 226) 0px 0px 0px 1px, rgb(217, 215, 226) 0px 1px 2px 0px;
+}
+.header-btn:hover {
+  box-shadow: rgb(255, 255, 255) 0px 0px 0px 0px, rgb(217, 215, 226) 0px 0px 0px 1px, rgb(217, 215, 226) 0px 1.0001px 2.00013px -0.0000327245px, rgba(0, 0, 0, 0) 0px 0.000065449px 0.000130898px -0.000065449px;
+}
+.md-typeset .headerlink:hover, .md-typeset .headerlink:target {
+  color: #8315F9;
+}
+.md-typeset h1, .md-header__title {
+  color: black;
+  font-weight: 800;
+}
+.md-typeset h1 {
+  font-weight: normal;
+  margin-bottom: 1rem;
+}
+body {
+  background: linear-gradient(to left bottom, rgb(243, 238, 255), rgb(255, 255, 255) 60%) no-repeat;
+}
+
+/* .md-nav__link:has([tabindex=""]) {
+  text-transform: uppercase;
+} */
+
+.header-list {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  list-style: none;
+  font-size: 0.75rem;
+  justify-content: flex-end;
+}
+.md-nav__list label, .md-nav--secondary label {
+  /* text-transform: uppercase; */
+  color: rgb(29, 29, 31) !important;
+  font-size: 0.7rem;
+  margin-bottom: 0;
+}
+.md-nav--secondary label {
+  margin-left: 0.5rem;
+}
+
+.md-nav__link {
+  padding: 0.25rem;
+  padding-left: 0.5rem;
+  padding-right: 0.5rem;
+}
+
+.md-nav__link--active {
+  background: rgb(243, 238, 255);
+  border-radius: 6px;
+  padding-top: 0.25rem;
+}
+
+.md-tabs__item--active {
+  color: var(--md-primary-fg-color);
+  border-bottom: 2px solid var(--md-primary-fg-color);
+}
+
+.md-nav--secondary .md-nav__title {
+  background: transparent;
+  box-shadow: none;
+}
+
+.md-header, .md-tabs {
+  color: rgb(111, 108, 121);
+  background-color: transparent;
+}
+.md-header--shadow {
+  background: linear-gradient(to left bottom, rgb(243, 238, 255), rgb(255, 255, 255) 60%);
+  box-shadow: none;
+  border-bottom: 1px solid rgb(229, 231, 235);
+}
+
+#item-logo {
+  display: none;
+}
+.md-main__inner, .md-header__inner, .md-grid {
+  max-width: 100%;
+}
+@media (max-width: 1200px) {
+  .md-header__inner {
+    display: flex;
+  }
+  .header-list {
+    display: none;
+  }
+  #item-logo {
+    display: block;
+  }
+}
+.md-content {
+  max-width: 40rem;
+  margin: auto;
+}
+/* // if no md-sidebar--primary, make .md-content full width */
+.md-main__inner:has(.md-sidebar--primary[hidden]) .md-content {
+  max-width: 100%;
+}
+.md-sidebar--primary {
+  flex: 0 20%;
+}
+.md-tabs {
+  border-bottom: 1px solid rgb(229, 231, 235);
+}
+.md-main__inner {
+  padding-top: 1rem;
+  margin-top: 0;
+}
 
 body.dark {
   /* Dark theme */
@@ -29,3 +228,43 @@ body[data-md-url$="/cookbooks/"] .md-content {
     margin-left: 0;
     width: 100%;
 }
+
+.md-main, nav .md-grid, .md-header__inner {
+  max-width: 1600px;
+  width: 100%;
+  margin: auto;
+}
+.md-search__scrollwrap {
+  width: 100% !important;
+}
+.md-nav--secondary .md-nav__title {
+  position: initial !important;
+}
+
+.md-header__title .md-ellipsis {
+  overflow: initial !important;
+  text-overflow: initial !important;
+}
+.md-search {
+  flex-grow: 0;
+}
+
+/* Table style */
+
+th, td {
+  border: 1px solid var(--md-typeset-table-color);
+}
+
+.md-typeset__table {
+  line-height: 1.5;
+}
+
+.md-typeset__table table:not([class]) {
+  font-size: 0.6rem;
+  border-collapse: collapse;
+}
+
+.md-typeset__table table:not([class]) td,
+.md-typeset__table table:not([class]) th {
+  padding: 10px;
+}

docs/theme/cookbooks.html

@@ -12,15 +12,15 @@
     </div>
     <div class="custom-grid">
       <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>
+          data-version="v0.26.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>
+          data-labels="ANNOTATORS,LINE ZONE,TRACKING" data-version="v0.26.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>
+          data-labels="ANNOTATORS,DETECTION,INFERENCE" data-version="v0.26.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"
@@ -28,7 +28,7 @@
       </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>
+          data-version="v0.26.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"
@@ -36,23 +36,23 @@
       </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>
+          data-version="v0.26.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>
+          data-labels="ANNOTATORS,YOLO WORLD" data-version="v0.26.0" 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>
+          data-labels="DETECTIONS,CSV SINK,INFERENCE" data-version="v0.26.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>
+          data-labels="DETECTIONS,JSON SINK,INFERENCE" data-version="v0.26.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>
+          data-labels="DETECTIONS,SAHI,SMALL,OBJECT,INFERENCE" data-version="v0.26.0" data-author="ediardo"></p>
       </a>
     </div>
   </div>

docs/theme/partials/header.html

@@ -0,0 +1,181 @@
+{% set class = "md-header" %}
+{% if "navigation.tabs.sticky" in features %}
+  {% set class = class ~ " md-header--shadow md-header--lifted" %}
+{% elif "navigation.tabs" not in features %}
+  {% set class = class ~ " md-header--shadow" %}
+{% endif %}
+
+<!-- Header -->
+<header class="{{ class }}" data-md-component="header">
+  <nav
+    class="md-header__inner md-grid"
+    aria-label="{{ lang.t('header') }}"
+  >
+
+    <!-- Link to home -->
+    <a
+      href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
+      title="{{ config.site_name | e }}"
+      class="md-header__button md-logo"
+      aria-label="{{ config.site_name }}"
+      data-md-component="logo"
+    >
+      {% include "partials/logo.html" %}
+    </a>
+
+    <!-- Button to open drawer -->
+    <label class="md-header__button md-icon" for="__drawer">
+      {% set icon = config.theme.icon.menu or "material/menu" %}
+      {% include ".icons/" ~ icon ~ ".svg" %}
+    </label>
+
+    <!-- Header title -->
+    <div class="md-header__title" data-md-component="header-title">
+      <div class="md-header__ellipsis">
+        <div class="md-header__topic">
+          <span class="md-ellipsis">
+            {{ config.site_name }} Docs
+          </span>
+        </div>
+        <div class="md-header__topic" data-md-component="header-topic">
+          <span class="md-ellipsis" style="display: flex; align-items: center; gap: 0.5rem;">
+            <a
+            href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
+            title="{{ config.site_name | e }}"
+            class="md-header__button md-logo"
+            aria-label="{{ config.site_name }}"
+            data-md-component="logo"
+            id="item-logo"
+            >
+            {% include "partials/logo.html" %}
+            </a>
+            {% if page.meta and page.meta.title %}
+              {{ page.meta.title }}
+            {% else %}
+              {{ page.title }}
+            {% endif %}
+          </span>
+        </div>
+      </div>
+    </div>
+    <!-- Button to open search modal -->
+    {% if "material/search" in config.plugins %}
+      {% set search = config.plugins["material/search"] | attr("config") %}
+
+      <!-- Check if search is actually enabled - see https://t.ly/DT_0V -->
+      {% if search.enabled %}
+        <label class="md-header__button md-icon" for="__search">
+          {% set icon = config.theme.icon.search or "material/magnify" %}
+          {% include ".icons/" ~ icon ~ ".svg" %}
+        </label>
+
+        <!-- Search interface -->
+        {% include "partials/search.html" %}
+      {% endif %}
+    {% endif %}
+
+
+    <ul class="header-list">
+        <li style="align-items: center;" id="resources-list">
+            <label for="dropdown-resources"><span>Resources <img src="https://ka-p.fontawesome.com/releases/v6.6.0/svgs/regular/chevron-down.svg?v=2&token=a463935e93" style="height: 0.5rem;" /></span></label>
+            <input type="radio" name="dropdown" id="dropdown-resources" style="display: none;" />
+            <ul class="resources-sublist sublist">
+                <li><a href="https://blog.roboflow.com">Blog</a></li>
+                <li><a href="https://discuss.roboflow.com">Community Forum</a></li>
+                <li><a href="https://roboflow.com/sales">Contact Sales</a></li>
+                <li><a href="https://universe.roboflow.com">Universe</a></li>
+            </ul>
+        </li>
+        <li style="align-items: center;" id="products-list">
+            <label for="dropdown-products"><span>Docs <img src="https://ka-p.fontawesome.com/releases/v6.6.0/svgs/regular/chevron-down.svg?v=2&token=a463935e93" style="height: 0.5rem;" /></span></label>
+            <input type="radio" name="dropdown" id="dropdown-products" style="display: none;" />
+            <ul class="products-sublist sublist">
+                <li><a href="https://inference.roboflow.com">Inference</a></li>
+                <li><a href="https://supervision.roboflow.com">Supervision</a></li>
+                <li><a href="https://trackers.roboflow.com">Trackers</a></li>
+                <li><a href="https://maestro.roboflow.com">Maestro</a></li>
+                <li><a href="https://docs.roboflow.com">Roboflow</a></li>
+            </ul>
+        </li>
+        <script>
+          document.addEventListener('click', function(event) {
+            const resourcesList = document.getElementById('resources-list');
+            const productsList = document.getElementById('products-list');
+            const dropdownResources = document.getElementById('dropdown-resources');
+            const dropdownProducts = document.getElementById('dropdown-products');
+
+            if (!resourcesList.contains(event.target)) {
+              dropdownResources.checked = false;
+            }
+            if (!productsList.contains(event.target)) {
+              dropdownProducts.checked = false;
+            }
+          });
+          // on mouse over
+          document.getElementById('resources-list').addEventListener('mouseover', function() {
+            document.getElementById('dropdown-resources').checked = true;
+          });
+          document.getElementById('products-list').addEventListener('mouseover', function() {
+            document.getElementById('dropdown-products').checked = true;
+          });
+          // on mouse out
+          document.getElementById('resources-list').addEventListener('mouseout', function() {
+            // if not hovering over the sublist or the label, uncheck the dropdown
+            // wait 1 sec
+            setTimeout(function() {
+              if (!document.querySelector('.resources-sublist:hover') && !document.querySelector('#resources-list:hover')) {
+                document.getElementById('dropdown-resources').checked = false;
+              }
+            }, 350);
+          });
+          // if mouseout of sublist, uncheck immediately
+          document.querySelector('.resources-sublist').addEventListener('mouseout', function() {
+            setTimeout(function() {
+              if (!document.querySelector('.resources-sublist:hover') && !document.querySelector('#resources-list:hover')) {
+                document.getElementById('dropdown-resources').checked = false;
+              }
+            }, 450);
+          });
+          document.getElementById('products-list').addEventListener('mouseout', function() {
+            // if not hovering over the sublist, uncheck the dropdown
+            // wait 1 sec
+            setTimeout(function() {
+              if (!document.querySelector('.products-sublist:hover') && !document.querySelector('#products-list:hover')) {
+                document.getElementById('dropdown-products').checked = false;
+              }
+            }, 500);
+          });
+          // if mouseout of sublist, uncheck immediately
+          document.querySelector('.products-sublist').addEventListener('mouseout', function() {
+            setTimeout(function() {
+              if (!document.querySelector('.products-sublist:hover') && !document.querySelector('#products-list:hover')) {
+                document.getElementById('dropdown-products').checked = false;
+              }
+            }, 500);
+          });
+
+        </script>
+        <style>
+          #dropdown-resources:checked ~ .resources-sublist {
+            display: block;
+          }
+          #dropdown-products:checked ~ .products-sublist {
+            display: block;
+          }
+          /* Hide dropdown if clicking outside */
+          body:not(:has(#dropdown-resources:checked)) .resources-sublist,
+          body:not(:has(#dropdown-products:checked)) .products-sublist {
+            display: none;
+          }
+        </style>
+        <a href="https://github.com/roboflow/supervision"><li class="header-btn" style="border-radius: 5px; color: white; background: var(--md-typeset-a-color); padding-top: 0.25rem; padding-left: 0.5rem; padding-bottom: 0.25rem; padding-right: 0.5rem; border: 1px solid #8315F9;">Go to GitHub</li></a>
+    </ul>
+  </nav>
+
+  <!-- Navigation tabs (sticky) -->
+  {% if "navigation.tabs.sticky" in features %}
+    {% if "navigation.tabs" in features %}
+      {% include "partials/tabs.html" %}
+    {% endif %}
+  {% endif %}
+</header>

docs/trackers.md

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

examples/count_people_in_zone/inference_example.py

@@ -1,7 +1,6 @@
 import argparse
 import json
 import os
-from typing import List, Tuple
 
 import cv2
 import numpy as np
@@ -14,7 +13,7 @@ import supervision as sv
 COLORS = sv.ColorPalette.DEFAULT
 
 
-def load_zones_config(file_path: str) -> List[np.ndarray]:
+def load_zones_config(file_path: str) -> list[np.ndarray]:
     """
     Load polygon zone configurations from a JSON file.
 
@@ -28,16 +27,14 @@ def load_zones_config(file_path: str) -> List[np.ndarray]:
     Returns:
     List[np.ndarray]: A list of polygons, each represented as a NumPy array.
     """
-    with open(file_path, "r") as file:
+    with open(file_path) as file:
         data = json.load(file)
         return [np.array(polygon, np.int32) for polygon in data["polygons"]]
 
 
 def initiate_annotators(
-    polygons: List[np.ndarray], resolution_wh: Tuple[int, int]
-) -> Tuple[
-    List[sv.PolygonZone], List[sv.PolygonZoneAnnotator], List[sv.BoundingBoxAnnotator]
-]:
+    polygons: list[np.ndarray], resolution_wh: tuple[int, int]
+) -> tuple[list[sv.PolygonZone], list[sv.PolygonZoneAnnotator], list[sv.BoxAnnotator]]:
     line_thickness = sv.calculate_optimal_line_thickness(resolution_wh=resolution_wh)
     text_scale = sv.calculate_optimal_text_scale(resolution_wh=resolution_wh)
 
@@ -54,7 +51,7 @@ def initiate_annotators(
             text_thickness=line_thickness * 2,
             text_scale=text_scale * 2,
         )
-        box_annotator = sv.BoundingBoxAnnotator(
+        box_annotator = sv.BoxAnnotator(
             color=COLORS.by_idx(index), thickness=line_thickness
         )
         zones.append(zone)
@@ -95,9 +92,9 @@ def detect(
 
 def annotate(
     frame: np.ndarray,
-    zones: List[sv.PolygonZone],
-    zone_annotators: List[sv.PolygonZoneAnnotator],
-    box_annotators: List[sv.BoundingBoxAnnotator],
+    zones: list[sv.PolygonZone],
+    zone_annotators: list[sv.PolygonZoneAnnotator],
+    box_annotators: list[sv.BoxAnnotator],
     detections: sv.Detections,
 ) -> np.ndarray:
     """
@@ -108,7 +105,7 @@ def annotate(
         zones (List[sv.PolygonZone]): A list of polygon zones used for detection.
         zone_annotators (List[sv.PolygonZoneAnnotator]): A list of annotators for
             drawing zone annotations.
-        box_annotators (List[sv.BoundingBoxAnnotator]): A list of annotators for
+        box_annotators (List[sv.BoxAnnotator]): A list of annotators for
             drawing box annotations.
         detections (sv.Detections): Detections to be used for annotation.
 

examples/count_people_in_zone/requirements.txt

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

examples/count_people_in_zone/ultralytics_example.py

@@ -1,6 +1,5 @@
 import argparse
 import json
-from typing import List, Tuple
 
 import cv2
 import numpy as np
@@ -12,7 +11,7 @@ import supervision as sv
 COLORS = sv.ColorPalette.DEFAULT
 
 
-def load_zones_config(file_path: str) -> List[np.ndarray]:
+def load_zones_config(file_path: str) -> list[np.ndarray]:
     """
     Load polygon zone configurations from a JSON file.
 
@@ -26,16 +25,14 @@ def load_zones_config(file_path: str) -> List[np.ndarray]:
     Returns:
     List[np.ndarray]: A list of polygons, each represented as a NumPy array.
     """
-    with open(file_path, "r") as file:
+    with open(file_path) as file:
         data = json.load(file)
         return [np.array(polygon, np.int32) for polygon in data["polygons"]]
 
 
 def initiate_annotators(
-    polygons: List[np.ndarray], resolution_wh: Tuple[int, int]
-) -> Tuple[
-    List[sv.PolygonZone], List[sv.PolygonZoneAnnotator], List[sv.BoundingBoxAnnotator]
-]:
+    polygons: list[np.ndarray], resolution_wh: tuple[int, int]
+) -> tuple[list[sv.PolygonZone], list[sv.PolygonZoneAnnotator], list[sv.BoxAnnotator]]:
     line_thickness = sv.calculate_optimal_line_thickness(resolution_wh=resolution_wh)
     text_scale = sv.calculate_optimal_text_scale(resolution_wh=resolution_wh)
 
@@ -52,7 +49,7 @@ def initiate_annotators(
             text_thickness=line_thickness * 2,
             text_scale=text_scale * 2,
         )
-        box_annotator = sv.BoundingBoxAnnotator(
+        box_annotator = sv.BoxAnnotator(
             color=COLORS.by_idx(index), thickness=line_thickness
         )
         zones.append(zone)
@@ -92,9 +89,9 @@ def detect(
 
 def annotate(
     frame: np.ndarray,
-    zones: List[sv.PolygonZone],
-    zone_annotators: List[sv.PolygonZoneAnnotator],
-    box_annotators: List[sv.BoundingBoxAnnotator],
+    zones: list[sv.PolygonZone],
+    zone_annotators: list[sv.PolygonZoneAnnotator],
+    box_annotators: list[sv.BoxAnnotator],
     detections: sv.Detections,
 ) -> np.ndarray:
     """
@@ -105,7 +102,7 @@ def annotate(
         zones (List[sv.PolygonZone]): A list of polygon zones used for detection.
         zone_annotators (List[sv.PolygonZoneAnnotator]): A list of annotators for
             drawing zone annotations.
-        box_annotators (List[sv.BoundingBoxAnnotator]): A list of annotators for
+        box_annotators (List[sv.BoxAnnotator]): A list of annotators for
             drawing box annotations.
         detections (sv.Detections): Detections to be used for annotation.
 
@@ -137,7 +134,7 @@ if __name__ == "__main__":
     )
     parser.add_argument(
         "--source_weights_path",
-        default="yolov8x.pt",
+        default="yolo11x.pt",
         help="Path to the source weights file",
         type=str,
     )

examples/heatmap_and_track/requirements.txt

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

examples/speed_estimation/requirements.txt

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

examples/speed_estimation/ultralytics_example.py

@@ -70,7 +70,7 @@ if __name__ == "__main__":
     args = parse_arguments()
 
     video_info = sv.VideoInfo.from_video_path(video_path=args.source_video_path)
-    model = YOLO("yolov8x.pt")
+    model = YOLO("yolo11x.pt")
 
     byte_track = sv.ByteTrack(
         frame_rate=video_info.fps, track_activation_threshold=args.confidence_threshold

examples/time_in_zone/inference_file_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -22,7 +21,7 @@ def main(
     model_id: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     model = get_model(model_id=model_id)
     tracker = sv.ByteTrack(minimum_matching_threshold=0.5)

examples/time_in_zone/inference_naive_stream_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -22,7 +21,7 @@ def main(
     model_id: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     model = get_model(model_id=model_id)
     tracker = sv.ByteTrack(minimum_matching_threshold=0.5)

examples/time_in_zone/inference_stream_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -18,7 +17,7 @@ LABEL_ANNOTATOR = sv.LabelAnnotator(
 
 
 class CustomSink:
-    def __init__(self, zone_configuration_path: str, classes: List[int]):
+    def __init__(self, zone_configuration_path: str, classes: list[int]):
         self.classes = classes
         self.tracker = sv.ByteTrack(minimum_matching_threshold=0.5)
         self.fps_monitor = sv.FPSMonitor()
@@ -83,7 +82,7 @@ def main(
     model_id: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     sink = CustomSink(zone_configuration_path=zone_configuration_path, classes=classes)
 

examples/time_in_zone/requirements.txt

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

examples/time_in_zone/scripts/download_from_youtube.py

@@ -1,11 +1,12 @@
+from __future__ import annotations
+
 import argparse
 import os
-from typing import Optional
 
 from pytube import YouTube
 
 
-def main(url: str, output_path: Optional[str], file_name: Optional[str]) -> None:
+def main(url: str, output_path: str | None, file_name: str | None) -> None:
     yt = YouTube(url)
     stream = yt.streams.get_highest_resolution()
 

examples/time_in_zone/scripts/draw_zones.py

@@ -1,7 +1,9 @@
+from __future__ import annotations
+
 import argparse
 import json
 import os
-from typing import Any, Optional, Tuple
+from typing import Any
 
 import cv2
 import numpy as np
@@ -19,10 +21,10 @@ COLORS = sv.ColorPalette.DEFAULT
 WINDOW_NAME = "Draw Zones"
 POLYGONS = [[]]
 
-current_mouse_position: Optional[Tuple[int, int]] = None
+current_mouse_position: tuple[int, int] | None = None
 
 
-def resolve_source(source_path: str) -> Optional[np.ndarray]:
+def resolve_source(source_path: str) -> np.ndarray | None:
     if not os.path.exists(source_path):
         return None
 

examples/time_in_zone/ultralytics_file_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -23,7 +22,7 @@ def main(
     device: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     model = YOLO(weights)
     tracker = sv.ByteTrack(minimum_matching_threshold=0.5)

examples/time_in_zone/ultralytics_naive_stream_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -23,7 +22,7 @@ def main(
     device: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     model = YOLO(weights)
     tracker = sv.ByteTrack(minimum_matching_threshold=0.5)

examples/time_in_zone/ultralytics_stream_example.py

@@ -1,5 +1,4 @@
 import argparse
-from typing import List
 
 import cv2
 import numpy as np
@@ -19,7 +18,7 @@ LABEL_ANNOTATOR = sv.LabelAnnotator(
 
 
 class CustomSink:
-    def __init__(self, zone_configuration_path: str, classes: List[int]):
+    def __init__(self, zone_configuration_path: str, classes: list[int]):
         self.classes = classes
         self.tracker = sv.ByteTrack(minimum_matching_threshold=0.8)
         self.fps_monitor = sv.FPSMonitor()
@@ -84,7 +83,7 @@ def main(
     device: str,
     confidence: float,
     iou: float,
-    classes: List[int],
+    classes: list[int],
 ) -> None:
     model = YOLO(weights)
 

examples/time_in_zone/utils/general.py

@@ -1,11 +1,11 @@
 import json
-from typing import Generator, List
+from collections.abc import Generator
 
 import cv2
 import numpy as np
 
 
-def load_zones_config(file_path: str) -> List[np.ndarray]:
+def load_zones_config(file_path: str) -> list[np.ndarray]:
     """
     Load polygon zone configurations from a JSON file.
 
@@ -19,12 +19,12 @@ def load_zones_config(file_path: str) -> List[np.ndarray]:
     Returns:
         List[np.ndarray]: A list of polygons, each represented as a NumPy array.
     """
-    with open(file_path, "r") as file:
+    with open(file_path) as file:
         data = json.load(file)
         return [np.array(polygon, np.int32) for polygon in data]
 
 
-def find_in_list(array: np.ndarray, search_list: List[int]) -> np.ndarray:
+def find_in_list(array: np.ndarray, search_list: list[int]) -> np.ndarray:
     """Determines if elements of a numpy array are present in a list.
 
     Args:

examples/time_in_zone/utils/timers.py

@@ -1,5 +1,4 @@
 from datetime import datetime
-from typing import Dict
 
 import numpy as np
 
@@ -26,7 +25,7 @@ class FPSBasedTimer:
         """
         self.fps = fps
         self.frame_id = 0
-        self.tracker_id2frame_id: Dict[int, int] = {}
+        self.tracker_id2frame_id: dict[int, int] = {}
 
     def tick(self, detections: sv.Detections) -> np.ndarray:
         """Processes the current frame, updating time durations for each tracker.
@@ -63,7 +62,7 @@ class ClockBasedTimer:
 
     def __init__(self) -> None:
         """Initializes the ClockBasedTimer."""
-        self.tracker_id2start_time: Dict[int, datetime] = {}
+        self.tracker_id2start_time: dict[int, datetime] = {}
 
     def tick(self, detections: sv.Detections) -> np.ndarray:
         """Processes the current frame, updating time durations for each tracker.

examples/tracking/inference_example.py

@@ -18,7 +18,7 @@ def process_video(
     model = get_roboflow_model(model_id=model_id, api_key=roboflow_api_key)
 
     tracker = sv.ByteTrack()
-    box_annotator = sv.BoundingBoxAnnotator()
+    box_annotator = sv.BoxAnnotator()
     label_annotator = sv.LabelAnnotator()
     frame_generator = sv.get_video_frames_generator(source_path=source_video_path)
     video_info = sv.VideoInfo.from_video_path(video_path=source_video_path)

examples/tracking/requirements.txt

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

examples/tracking/ultralytics_example.py

@@ -16,7 +16,7 @@ def process_video(
     model = YOLO(source_weights_path)
 
     tracker = sv.ByteTrack()
-    box_annotator = sv.BoundingBoxAnnotator()
+    box_annotator = sv.BoxAnnotator()
     label_annotator = sv.LabelAnnotator()
     frame_generator = sv.get_video_frames_generator(source_path=source_video_path)
     video_info = sv.VideoInfo.from_video_path(video_path=source_video_path)

examples/traffic_analysis/inference_example.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 import argparse
 import os
-from typing import Dict, Iterable, List, Optional, Set
+from collections.abc import Iterable
 
 import cv2
 import numpy as np
@@ -29,14 +31,14 @@ ZONE_OUT_POLYGONS = [
 
 class DetectionsManager:
     def __init__(self) -> None:
-        self.tracker_id_to_zone_id: Dict[int, int] = {}
-        self.counts: Dict[int, Dict[int, Set[int]]] = {}
+        self.tracker_id_to_zone_id: dict[int, int] = {}
+        self.counts: dict[int, dict[int, set[int]]] = {}
 
     def update(
         self,
         detections_all: sv.Detections,
-        detections_in_zones: List[sv.Detections],
-        detections_out_zones: List[sv.Detections],
+        detections_in_zones: list[sv.Detections],
+        detections_out_zones: list[sv.Detections],
     ) -> sv.Detections:
         for zone_in_id, detections_in_zone in enumerate(detections_in_zones):
             for tracker_id in detections_in_zone.tracker_id:
@@ -59,9 +61,9 @@ class DetectionsManager:
 
 
 def initiate_polygon_zones(
-    polygons: List[np.ndarray],
+    polygons: list[np.ndarray],
     triggering_anchors: Iterable[sv.Position] = [sv.Position.CENTER],
-) -> List[sv.PolygonZone]:
+) -> list[sv.PolygonZone]:
     return [
         sv.PolygonZone(
             polygon=polygon,
@@ -77,7 +79,7 @@ class VideoProcessor:
         roboflow_api_key: str,
         model_id: str,
         source_video_path: str,
-        target_video_path: Optional[str] = None,
+        target_video_path: str | None = None,
         confidence_threshold: float = 0.3,
         iou_threshold: float = 0.7,
     ) -> None:

examples/traffic_analysis/requirements.txt

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

examples/traffic_analysis/ultralytics_example.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 import argparse
-from typing import Dict, Iterable, List, Optional, Set
+from collections.abc import Iterable
 
 import cv2
 import numpy as np
@@ -27,14 +29,14 @@ ZONE_OUT_POLYGONS = [
 
 class DetectionsManager:
     def __init__(self) -> None:
-        self.tracker_id_to_zone_id: Dict[int, int] = {}
-        self.counts: Dict[int, Dict[int, Set[int]]] = {}
+        self.tracker_id_to_zone_id: dict[int, int] = {}
+        self.counts: dict[int, dict[int, set[int]]] = {}
 
     def update(
         self,
         detections_all: sv.Detections,
-        detections_in_zones: List[sv.Detections],
-        detections_out_zones: List[sv.Detections],
+        detections_in_zones: list[sv.Detections],
+        detections_out_zones: list[sv.Detections],
     ) -> sv.Detections:
         for zone_in_id, detections_in_zone in enumerate(detections_in_zones):
             for tracker_id in detections_in_zone.tracker_id:
@@ -57,9 +59,9 @@ class DetectionsManager:
 
 
 def initiate_polygon_zones(
-    polygons: List[np.ndarray],
+    polygons: list[np.ndarray],
     triggering_anchors: Iterable[sv.Position] = [sv.Position.CENTER],
-) -> List[sv.PolygonZone]:
+) -> list[sv.PolygonZone]:
     return [
         sv.PolygonZone(
             polygon=polygon,
@@ -74,7 +76,7 @@ class VideoProcessor:
         self,
         source_weights_path: str,
         source_video_path: str,
-        target_video_path: Optional[str] = None,
+        target_video_path: str | None = None,
         confidence_threshold: float = 0.3,
         iou_threshold: float = 0.7,
     ) -> None:

mkdocs.yml

@@ -3,9 +3,8 @@ site_url: https://supervision.roboflow.com/
 site_author: Roboflow
 site_description: A set of easy-to-use utilities that will come in handy in any computer vision project.
 repo_name: roboflow/supervision
-repo_url: https://github.com/roboflow/supervision
 edit_uri: https://github.com/roboflow/supervision/tree/main/docs
-copyright: Roboflow 2024. All rights reserved.
+copyright: Roboflow 2025. All rights reserved.
 
 extra:
   social:
@@ -13,12 +12,8 @@ extra:
       link: https://github.com/roboflow
     - icon: fontawesome/brands/python
       link: https://pypi.org/project/supervision
-    - icon: fontawesome/brands/docker
-      link: https://hub.docker.com/u/roboflow
     - icon: fontawesome/brands/youtube
       link: https://www.youtube.com/roboflow
-    - icon: fontawesome/brands/linkedin
-      link: https://www.linkedin.com/company/roboflow-ai/
     - icon: fontawesome/brands/x-twitter
       link: https://twitter.com/roboflow
     - icon: fontawesome/brands/discord
@@ -34,7 +29,7 @@ extra_css:
   - stylesheets/cookbooks-card.css
 
 nav:
-  - Supervision: index.md
+  - Home: index.md
   - Learn:
       - Detect and Annotate: how_to/detect_and_annotate.md
       - Save Detections: how_to/save_detections.md
@@ -43,13 +38,15 @@ nav:
       - Track Objects on Video: how_to/track_objects.md
       - Process Datasets: how_to/process_datasets.md
       - Benchmark a Model: how_to/benchmark_a_model.md
-
-  - Reference - Code API:
+  - Reference:
       - Detection and Segmentation:
           - Core: detection/core.md
           - Annotators: detection/annotators.md
-          - Double Detection Filter: detection/double_detection_filter.md
-          - Utils: detection/utils.md
+          - Converters: detection/utils/converters.md
+          - IoU and NMS: detection/utils/iou_and_nms.md
+          - Boxes: detection/utils/boxes.md
+          - Masks: detection/utils/masks.md
+          - Polygons: detection/utils/polygons.md
       - Keypoint Detection:
           - Core: keypoint/core.md
           - Annotators: keypoint/annotators.md
@@ -83,12 +80,7 @@ nav:
           - 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
-  - Release Notes:
+  - Changelog:
       - Changelog: changelog.md
       - Deprecated: deprecated.md
 
@@ -106,6 +98,7 @@ theme:
     - content.tooltips
     - content.code.annotate
     - navigation.tabs
+    - navigation.tabs.sticky
 
   palette:
     # Palette for light mode
@@ -123,11 +116,8 @@ theme:
         name: Switch to light mode
 
   font:
-    text: Roboto
-    code: Roboto Mono
-    features:
-      - content.code.copy
-      - content.code.annotate
+    text: Inter
+    code: IBM Plex Mono
 
 plugins:
   - search
@@ -149,9 +139,12 @@ plugins:
             group_by_category: true
             docstring_style: google
             show_symbol_type_heading: true
+            show_root_heading: True
             show_symbol_type_toc: true
             show_category_heading: true
-          domains: [std, py]
+          inventories:
+          - url: https://docs.python-requests.org/en/master/objects.inv
+            domains: [std, py]
   - git-committers:
       repository: roboflow/supervision
       branch: develop
@@ -176,11 +169,18 @@ markdown_extensions:
       check_paths: true
   - pymdownx.highlight:
       anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.arithmatex:
+      generic: true
 
 extra_javascript:
   - "javascripts/init_kapa_widget.js"
   - "javascripts/cookbooks-card.js"
+  - "javascripts/segment.js"
+  - "javascripts/mathjax.js"
   - "https://cdnjs.cloudflare.com/ajax/libs/dompurify/3.0.8/purify.min.js"
+  - "https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"
 
 # Messages shown during document build
 # Reference: https://www.mkdocs.org/user-guide/configuration/#validation

pyproject.toml

@@ -2,9 +2,9 @@
 name = "supervision"
 description = "A set of easy-to-use utils that will come in handy in any Computer Vision project"
 license = { text = "MIT" }
-version = "0.26.0rc3"
+version = "0.26.0"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 authors = [
     { name = "Piotr Skalski", email = "piotr.skalski92@gmail.com" }
 ]
@@ -38,12 +38,8 @@ classifiers = [
     'Operating System :: MacOS',
 ]
 dependencies = [
-    "numpy>=1.21.2,<1.26.0; python_version < '3.12'",
-    "numpy>=1.26.0,<2.1.0; python_version >= '3.12' and python_version < '3.13'",
-    "numpy>=2.1.0; python_version >= '3.13'",
-    "scipy (==1.10.0); python_version < '3.9'",
-    "scipy (>=1.10.0,<1.14.1) ; python_version >= '3.9' and python_version < '3.13'",
-    "scipy (>=1.14.1); python_version >= '3.13'",
+    "numpy>=1.21.2",
+    "scipy>=1.10.0",
     "matplotlib>=3.6.0",
     "pyyaml>=5.3",
     "defusedxml>=0.7.1",
@@ -60,51 +56,44 @@ Documentation = "https://supervision.roboflow.com/latest/"
 
 [project.optional-dependencies]
 metrics = [
-    "pandas>=2.0.0; python_version < '3.13'",
-    "pandas>=2.2.3; python_version >= '3.13'"
+    "pandas>=2.0.0",
 ]
 
-[tool.poetry]
-# Keep version here since it's dynamic
-packages = [{ include = "supervision" }, { include = "supervision/py.typed" }]
-
-
-[tool.poetry.group.dev.dependencies]
-pytest = ">=7.2.2,<9.0.0"
-tox = ">=4.11.4"
-notebook = ">=6.5.3,<8.0.0"
-ipywidgets = ">=8.1.1"
-jupytext = ">=1.16.1"
-nbconvert = ">=7.14.2"
-docutils = "!=0.21"
-
-[tool.poetry.group.docs.dependencies]
-mkdocs-material = { extras = ["imaging"], version = "^9.5.5" }
-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 = { version = ">=2.4.1", python = ">=3.8,<4" }
-mkdocs-git-revision-date-localized-plugin = ">=1.2.4"
-
-[tool.poetry.group.build.dependencies]
-twine = ">=5.1.1,<7.0.0"
-wheel = ">=0.40,<0.46"
-build = ">=0.10,<1.3"
+[dependency-groups]
+dev = [
+    "pytest>=7.2.2,<9.0.0",
+    "tox>=4.11.4",
+    "notebook>=6.5.3,<8.0.0",
+    "ipywidgets>=8.1.1",
+    "jupytext>=1.16.1",
+    "nbconvert>=7.14.2",
+    "docutils!=0.21"
+]
+docs = [
+    "mkdocs-material[imaging]>=9.5.5",
+    "mkdocstrings>=0.25.2,<0.30.0",
+    "mkdocstrings-python>=1.10.9",
+    "mike>=2.0.0",
+    "mkdocs-jupyter>=0.24.3",
+    "mkdocs-git-committers-plugin-2>=2.4.1; python_version >= '3.9' and python_version < '4'",
+    "mkdocs-git-revision-date-localized-plugin>=1.2.4"
+]
+build = [
+    "twine>=5.1.1,<7.0.0",
+    "wheel>=0.40,<0.46",
+    "build>=0.10,<1.3"
+]
 
 [tool.bandit]
 target = ["test", "supervision"]
-tests = ["B201", "B301", "B318", "B314", "B303", "B413", "B412", "B410"]
+tests = ["B201", "B301", "B318", "B314", "B303", "B413", "B412"]
 
 [tool.autoflake]
 check = true
 imports = ["cv2", "supervision"]
 
-
 [tool.ruff]
-target-version = "py38"
+target-version = "py39"
 
 # Exclude a variety of commonly ignored directories.
 exclude = [
@@ -139,7 +128,7 @@ indent-width = 4
 
 [tool.ruff.lint]
 # Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default.
-select = ["E", "F", "I", "A", "Q", "W", "RUF"]
+select = ["E", "F", "I", "A", "Q", "W", "RUF", "UP"]
 ignore = []
 # Allow autofix for all enabled rules (when `--fix`) is provided.
 fixable = [
@@ -226,7 +215,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.codespell]
-skip = "*.ipynb,poetry.lock"
+skip = "*.ipynb"
 count = true
 quiet-level = 3
 ignore-words-list = "STrack,sTrack,strack"
@@ -235,8 +224,12 @@ ignore-words-list = "STrack,sTrack,strack"
 include-package-data = false
 
 [tool.setuptools.packages.find]
+include = ["supervision*"]
 exclude = ["docs*", "test*", "examples*"]
 
+[tool.setuptools.package-data]
+supervision = ["py.typed"]
+
 [build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"
+requires = ["setuptools >= 61.0"]
+build-backend = "setuptools.build_meta"

supervision/__init__.py

@@ -9,7 +9,6 @@ except importlib_metadata.PackageNotFoundError:
 from supervision.annotators.core import (
     BackgroundOverlayAnnotator,
     BlurAnnotator,
-    BoundingBoxAnnotator,
     BoxAnnotator,
     BoxCornerAnnotator,
     CircleAnnotator,
@@ -39,6 +38,7 @@ from supervision.dataset.core import (
     ClassificationDataset,
     DetectionDataset,
 )
+from supervision.dataset.formats.coco import get_coco_class_index_mapping
 from supervision.dataset.utils import mask_to_rle, rle_to_mask
 from supervision.detection.core import Detections
 from supervision.detection.line_zone import (
@@ -46,39 +46,53 @@ from supervision.detection.line_zone import (
     LineZoneAnnotator,
     LineZoneAnnotatorMulticlass,
 )
-from supervision.detection.lmm import LMM
-from supervision.detection.overlap_filter import (
-    OverlapFilter,
-    box_non_max_merge,
-    box_non_max_suppression,
-    mask_non_max_suppression,
-)
 from supervision.detection.tools.csv_sink import CSVSink
 from supervision.detection.tools.inference_slicer import InferenceSlicer
 from supervision.detection.tools.json_sink import JSONSink
 from supervision.detection.tools.polygon_zone import PolygonZone, PolygonZoneAnnotator
 from supervision.detection.tools.smoother import DetectionsSmoother
-from supervision.detection.utils import (
-    box_iou_batch,
-    calculate_masks_centroids,
+from supervision.detection.utils.boxes import (
     clip_boxes,
-    contains_holes,
-    contains_multiple_segments,
-    filter_polygons_by_area,
-    mask_iou_batch,
+    denormalize_boxes,
+    move_boxes,
+    pad_boxes,
+    scale_boxes,
+)
+from supervision.detection.utils.converters import (
     mask_to_polygons,
     mask_to_xyxy,
-    move_boxes,
-    move_masks,
-    oriented_box_iou_batch,
-    pad_boxes,
     polygon_to_mask,
     polygon_to_xyxy,
-    scale_boxes,
     xcycwh_to_xyxy,
     xywh_to_xyxy,
     xyxy_to_polygons,
+    xyxy_to_xcycarh,
+    xyxy_to_xywh,
 )
+from supervision.detection.utils.iou_and_nms import (
+    OverlapFilter,
+    OverlapMetric,
+    box_iou,
+    box_iou_batch,
+    box_iou_batch_with_jaccard,
+    box_non_max_merge,
+    box_non_max_suppression,
+    mask_iou_batch,
+    mask_non_max_merge,
+    mask_non_max_suppression,
+    oriented_box_iou_batch,
+)
+from supervision.detection.utils.masks import (
+    calculate_masks_centroids,
+    contains_holes,
+    contains_multiple_segments,
+    move_masks,
+)
+from supervision.detection.utils.polygons import (
+    approximate_polygon,
+    filter_polygons_by_area,
+)
+from supervision.detection.vlm import LMM, VLM
 from supervision.draw.color import Color, ColorPalette
 from supervision.draw.utils import (
     calculate_optimal_line_thickness,
@@ -126,7 +140,6 @@ __all__ = [
     "BackgroundOverlayAnnotator",
     "BaseDataset",
     "BlurAnnotator",
-    "BoundingBoxAnnotator",
     "BoxAnnotator",
     "BoxCornerAnnotator",
     "ByteTrack",
@@ -163,6 +176,7 @@ __all__ = [
     "MeanAveragePrecision",
     "OrientedBoxAnnotator",
     "OverlapFilter",
+    "OverlapMetric",
     "PercentageBarAnnotator",
     "PixelateAnnotator",
     "Point",
@@ -179,7 +193,10 @@ __all__ = [
     "VertexLabelAnnotator",
     "VideoInfo",
     "VideoSink",
+    "approximate_polygon",
+    "box_iou",
     "box_iou_batch",
+    "box_iou_batch_with_jaccard",
     "box_non_max_merge",
     "box_non_max_suppression",
     "calculate_masks_centroids",
@@ -199,11 +216,13 @@ __all__ = [
     "draw_rectangle",
     "draw_text",
     "filter_polygons_by_area",
+    "get_coco_class_index_mapping",
     "get_polygon_center",
     "get_video_frames_generator",
     "letterbox_image",
     "list_files_with_extensions",
     "mask_iou_batch",
+    "mask_non_max_merge",
     "mask_non_max_suppression",
     "mask_to_polygons",
     "mask_to_rle",
@@ -226,4 +245,6 @@ __all__ = [
     "xcycwh_to_xyxy",
     "xywh_to_xyxy",
     "xyxy_to_polygons",
+    "xyxy_to_xcycarh",
+    "xyxy_to_xywh",
 ]

supervision/annotators/utils.py

@@ -1,12 +1,18 @@
+from __future__ import annotations
+
+import textwrap
 from enum import Enum
-from typing import Optional, Tuple, Union
 
 import numpy as np
 
+from supervision.config import CLASS_NAME_DATA_FIELD
 from supervision.detection.core import Detections
 from supervision.draw.color import Color, ColorPalette
 from supervision.geometry.core import Position
 
+PENDING_TRACK_COLOR = Color.GREY
+PENDING_TRACK_ID = -1
+
 
 class ColorLookup(Enum):
     """
@@ -30,7 +36,7 @@ class ColorLookup(Enum):
 def resolve_color_idx(
     detections: Detections,
     detection_idx: int,
-    color_lookup: Union[ColorLookup, np.ndarray] = ColorLookup.CLASS,
+    color_lookup: ColorLookup | np.ndarray = ColorLookup.CLASS,
 ) -> int:
     if detection_idx >= len(detections):
         raise ValueError(
@@ -67,10 +73,10 @@ def resolve_color_idx(
 
 
 def resolve_text_background_xyxy(
-    center_coordinates: Tuple[int, int],
-    text_wh: Tuple[int, int],
+    center_coordinates: tuple[int, int],
+    text_wh: tuple[int, int],
     position: Position,
-) -> Tuple[int, int, int, int]:
+) -> tuple[int, int, int, int]:
     center_x, center_y = center_coordinates
     text_w, text_h = text_wh
 
@@ -119,30 +125,192 @@ def resolve_text_background_xyxy(
         )
 
 
-def get_color_by_index(color: Union[Color, ColorPalette], idx: int) -> Color:
+def get_color_by_index(color: Color | ColorPalette, idx: int) -> Color:
     if isinstance(color, ColorPalette):
         return color.by_idx(idx)
     return color
 
 
 def resolve_color(
-    color: Union[Color, ColorPalette],
+    color: Color | ColorPalette,
     detections: Detections,
     detection_idx: int,
-    color_lookup: Union[ColorLookup, np.ndarray] = ColorLookup.CLASS,
+    color_lookup: ColorLookup | np.ndarray = ColorLookup.CLASS,
 ) -> Color:
     idx = resolve_color_idx(
         detections=detections,
         detection_idx=detection_idx,
         color_lookup=color_lookup,
     )
+    if color_lookup == ColorLookup.TRACK and idx == PENDING_TRACK_ID:
+        return PENDING_TRACK_COLOR
     return get_color_by_index(color=color, idx=idx)
 
 
+def wrap_text(text: str, max_line_length=None) -> list[str]:
+    """
+    Wraps text to the specified maximum line length, respecting existing newlines.
+    Uses the textwrap library for robust text wrapping.
+
+    Args:
+        text (str): The text to wrap.
+
+    Returns:
+        List[str]: A list of text lines after wrapping.
+    """
+
+    if not text:
+        return [""]
+
+    if max_line_length is None:
+        return text.splitlines() or [""]
+
+    paragraphs = text.split("\n")
+    all_lines = []
+
+    for paragraph in paragraphs:
+        if not paragraph:
+            # Keep empty lines
+            all_lines.append("")
+            continue
+
+        wrapped = textwrap.wrap(
+            paragraph,
+            width=max_line_length,
+            break_long_words=True,
+            replace_whitespace=False,
+            drop_whitespace=True,
+        )
+
+        if wrapped:
+            all_lines.extend(wrapped)
+        else:
+            all_lines.append("")
+
+    return all_lines if all_lines else [""]
+
+
+def validate_labels(labels: list[str] | None, detections: Detections):
+    """
+    Validates that the number of provided labels matches the number of detections.
+
+    Args:
+        labels (Optional[List[str]]): A list of labels, one for each detection. Can
+                                        be None.
+        detections (Detections): The detections to be labeled.
+
+    Raises:
+        ValueError: If `labels` is not None and its length does not match the number
+        of detections.
+    """
+    if labels is not None and len(labels) != len(detections):
+        raise ValueError(
+            f"The number of labels ({len(labels)}) does not match the "
+            f"number of detections ({len(detections)}). Each detection "
+            f"should have exactly 1 label."
+        )
+
+
+def get_labels_text(
+    detections: Detections, custom_labels: list[str] | None
+) -> list[str]:
+    """
+    Retrieves the text labels for the detections.
+
+    If `custom_labels` are provided, they are used. Otherwise, the labels are
+    extracted from the `detections` object, prioritizing the 'class_name' field,
+    then the `class_id`, and finally using the detection index as a string.
+
+    Args:
+        detections (Detections): The detections to get labels for.
+        custom_labels (Optional[List[str]]): An optional list of custom labels.
+
+    Returns:
+        List[str]: A list of text labels for each detection.
+    """
+    if custom_labels is not None:
+        return custom_labels
+
+    labels = []
+    for idx in range(len(detections)):
+        if CLASS_NAME_DATA_FIELD in detections.data:
+            labels.append(detections.data[CLASS_NAME_DATA_FIELD][idx])
+        elif detections.class_id is not None:
+            labels.append(str(detections.class_id[idx]))
+        else:
+            labels.append(str(idx))
+    return labels
+
+
+def snap_boxes(xyxy: np.ndarray, resolution_wh: tuple[int, int]) -> np.ndarray:
+    """
+    Shifts `label` bounding boxes into the frame so that they are fully contained
+    within the given resolution, prioritizing the top/left edge.
+    Unlike `clip_boxes`, this function does not crop boxes.
+    It moves them entirely if they exceed the frame boundaries.
+
+    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)`.
+        resolution_wh (Tuple[int, int]): A tuple `(width, height)`
+            representing the resolution of the frame.
+
+    Returns:
+        np.ndarray: A numpy array of shape `(N, 4)` with boxes shifted into frame.
+
+    Examples:
+    ```python
+    import numpy as np
+
+    # Example boxes:
+    xyxy = np.array([
+        [-10, 10, 30, 50],     # Off left edge
+        [310, 200, 350, 250],  # Off right edge
+        [100, -20, 150, 30],   # Off top edge
+        [200, 220, 250, 270],  # Off bottom edge
+        [-20, 10, 350, 50],    # Wider than frame (370 vs 320)
+        [10, -20, 30, 260]     # Taller than frame (280 vs 240)
+    ])
+
+    resolution_wh = (320, 240)
+    snapped_boxes = snap_boxes(xyxy=xyxy, resolution_wh=resolution_wh)
+
+    # Results:
+    # [[  0  10  40  50]  # Left edge shifted right
+    #  [280 200 320 250]  # Right edge shifted left
+    #  [100   0 150  50]  # Top edge shifted down
+    #  [200 190 250 240]  # Bottom edge shifted up
+    #  [  0  10 370  50]  # Wide box aligned to left edge
+    #  [ 10   0  30 280]] # Tall box aligned to top edge
+    ```
+    """
+    result = np.copy(xyxy)
+    width, height = resolution_wh
+
+    # X-axis (prioritize left edge)
+    left_overflow = result[:, 0] < 0
+    result[left_overflow, 0:3:2] -= result[left_overflow, 0:1]
+
+    right_overflow = (~left_overflow) & (result[:, 2] > width)
+    right_shift = width - result[right_overflow, 2]
+    result[right_overflow, 0:3:2] += right_shift[:, np.newaxis]
+
+    # Y-axis (prioritize top edge)
+    top_overflow = result[:, 1] < 0
+    result[top_overflow, 1:4:2] -= result[top_overflow, 1:2]
+
+    bottom_overflow = (~top_overflow) & (result[:, 3] > height)
+    bottom_shift = height - result[bottom_overflow, 3]
+    result[bottom_overflow, 1:4:2] += bottom_shift[:, np.newaxis]
+
+    return result
+
+
 class Trace:
     def __init__(
         self,
-        max_size: Optional[int] = None,
+        max_size: int | None = None,
         start_frame_id: int = 0,
         anchor: Position = Position.CENTER,
     ) -> None:
@@ -158,7 +326,10 @@ class Trace:
         frame_id = np.full(len(detections), self.current_frame_id, dtype=int)
         self.frame_id = np.concatenate([self.frame_id, frame_id])
         self.xy = np.concatenate(
-            [self.xy, detections.get_anchors_coordinates(self.anchor)]
+            [
+                self.xy,
+                detections.get_anchors_coordinates(self.anchor),
+            ]
         )
         self.tracker_id = np.concatenate([self.tracker_id, detections.tracker_id])
 

supervision/assets/downloader.py

@@ -1,8 +1,9 @@
+from __future__ import annotations
+
 import os
 from hashlib import new as hash_new
 from pathlib import Path
 from shutil import copyfileobj
-from typing import Union
 
 from requests import get
 from tqdm.auto import tqdm
@@ -32,7 +33,7 @@ def is_md5_hash_matching(filename: str, original_md5_hash: str) -> bool:
     return computed_md5_hash.hexdigest() == original_md5_hash
 
 
-def download_assets(asset_name: Union[VideoAssets, str]) -> str:
+def download_assets(asset_name: VideoAssets | str) -> str:
     """
     Download a specified asset if it doesn't already exist or is corrupted.
 

supervision/assets/list.py

@@ -1,5 +1,4 @@
 from enum import Enum
-from typing import Dict, Tuple
 
 BASE_VIDEO_URL = "https://media.roboflow.com/supervision/video-examples/"
 
@@ -39,7 +38,7 @@ class VideoAssets(Enum):
         return list(map(lambda c: c.value, cls))
 
 
-VIDEO_ASSETS: Dict[str, Tuple[str, str]] = {
+VIDEO_ASSETS: dict[str, tuple[str, str]] = {
     VideoAssets.VEHICLES.value: (
         f"{BASE_VIDEO_URL}{VideoAssets.VEHICLES.value}",
         "8155ff4e4de08cfa25f39de96483f918",

supervision/classification/core.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Optional, Tuple
+from typing import Any
 
 import numpy as np
 
@@ -28,7 +28,7 @@ def _validate_confidence(confidence: Any, n: int) -> None:
 @dataclass
 class Classifications:
     class_id: np.ndarray
-    confidence: Optional[np.ndarray] = None
+    confidence: np.ndarray | None = None
 
     def __post_init__(self) -> None:
         """
@@ -154,7 +154,7 @@ class Classifications:
         class_id = np.arange(len(confidence))
         return cls(class_id=class_id, confidence=confidence)
 
-    def get_top_k(self, k: int) -> Tuple[np.ndarray, np.ndarray]:
+    def get_top_k(self, k: int) -> tuple[np.ndarray, np.ndarray]:
         """
         Retrieve the top k class IDs and confidences,
             ordered in descending order by confidence.

supervision/dataset/core.py

@@ -2,10 +2,10 @@ from __future__ import annotations
 
 import os
 from abc import ABC, abstractmethod
+from collections.abc import Iterator
 from dataclasses import dataclass
 from itertools import chain
 from pathlib import Path
-from typing import Dict, Iterator, List, Optional, Tuple, Union
 
 import cv2
 import numpy as np
@@ -32,7 +32,7 @@ from supervision.dataset.utils import (
     train_test_split,
 )
 from supervision.detection.core import Detections
-from supervision.utils.internal import deprecated, warn_deprecated
+from supervision.utils.internal import warn_deprecated
 from supervision.utils.iterables import find_duplicates
 
 
@@ -45,9 +45,9 @@ class BaseDataset(ABC):
     def split(
         self,
         split_ratio: float = 0.8,
-        random_state: Optional[int] = None,
+        random_state: int | None = None,
         shuffle: bool = True,
-    ) -> Tuple[BaseDataset, BaseDataset]:
+    ) -> tuple[BaseDataset, BaseDataset]:
         pass
 
 
@@ -71,9 +71,9 @@ class DetectionDataset(BaseDataset):
 
     def __init__(
         self,
-        classes: List[str],
-        images: Union[List[str], Dict[str, np.ndarray]],
-        annotations: Dict[str, Detections],
+        classes: list[str],
+        images: list[str] | dict[str, np.ndarray],
+        annotations: dict[str, Detections],
     ) -> None:
         self.classes = classes
 
@@ -86,40 +86,7 @@ class DetectionDataset(BaseDataset):
         # Eliminate duplicates while preserving order
         self.image_paths = list(dict.fromkeys(images))
 
-        self._images_in_memory: Dict[str, np.ndarray] = {}
-        if isinstance(images, dict):
-            self._images_in_memory = images
-            warn_deprecated(
-                "Passing a `Dict[str, np.ndarray]` into `DetectionDataset` is "
-                "deprecated and will be removed in `supervision-0.26.0`. Use "
-                "a list of paths `List[str]` instead."
-            )
-            # TODO: when supervision-0.26.0 is released, and Dict[str, np.ndarray]
-            #       for images is no longer supported, also simplify the rest of
-            #       the code. E.g. list(images) is no longer needed, and merge can
-            #       be simplified.
-
-    @property
-    @deprecated(
-        "`DetectionDataset.images` property is deprecated and will be removed in "
-        "`supervision-0.26.0`. Iterate with `for path, image, annotation in dataset:` "
-        "instead."
-    )
-    def images(self) -> Dict[str, np.ndarray]:
-        """
-        Load all images to memory and return them as a dictionary.
-
-        !!! warning
-
-            Only use this when you need all images at once.
-            It is much more memory-efficient to initialize dataset with
-            image paths and use `for path, image, annotation in dataset:`.
-        """
-        if self._images_in_memory:
-            return self._images_in_memory
-
-        images = {image_path: cv2.imread(image_path) for image_path in self.image_paths}
-        return images
+        self._images_in_memory: dict[str, np.ndarray] = {}
 
     def _get_image(self, image_path: str) -> np.ndarray:
         """Assumes that image is in dataset"""
@@ -130,7 +97,7 @@ class DetectionDataset(BaseDataset):
     def __len__(self) -> int:
         return len(self._images_in_memory) or len(self.image_paths)
 
-    def __getitem__(self, i: int) -> Tuple[str, np.ndarray, Detections]:
+    def __getitem__(self, i: int) -> tuple[str, np.ndarray, Detections]:
         """
         Returns:
             Tuple[str, np.ndarray, Detections]: The image path, image data,
@@ -141,7 +108,7 @@ class DetectionDataset(BaseDataset):
         annotation = self.annotations[image_path]
         return image_path, image, annotation
 
-    def __iter__(self) -> Iterator[Tuple[str, np.ndarray, Detections]]:
+    def __iter__(self) -> Iterator[tuple[str, np.ndarray, Detections]]:
         """
         Iterate over the images and annotations in the dataset.
 
@@ -179,9 +146,9 @@ class DetectionDataset(BaseDataset):
     def split(
         self,
         split_ratio: float = 0.8,
-        random_state: Optional[int] = None,
+        random_state: int | None = None,
         shuffle: bool = True,
-    ) -> Tuple[DetectionDataset, DetectionDataset]:
+    ) -> tuple[DetectionDataset, DetectionDataset]:
         """
         Splits the dataset into two parts (training and testing)
             using the provided split_ratio.
@@ -215,8 +182,8 @@ class DetectionDataset(BaseDataset):
             shuffle=shuffle,
         )
 
-        train_input: Union[List[str], Dict[str, np.ndarray]]
-        test_input: Union[List[str], Dict[str, np.ndarray]]
+        train_input: list[str] | dict[str, np.ndarray]
+        test_input: list[str] | dict[str, np.ndarray]
         if self._images_in_memory:
             train_input = {path: self._images_in_memory[path] for path in train_paths}
             test_input = {path: self._images_in_memory[path] for path in test_paths}
@@ -239,7 +206,7 @@ class DetectionDataset(BaseDataset):
         return train_dataset, test_dataset
 
     @classmethod
-    def merge(cls, dataset_list: List[DetectionDataset]) -> DetectionDataset:
+    def merge(cls, dataset_list: list[DetectionDataset]) -> DetectionDataset:
         """
         Merge a list of `DetectionDataset` objects into a single
             `DetectionDataset` object.
@@ -333,8 +300,8 @@ class DetectionDataset(BaseDataset):
 
     def as_pascal_voc(
         self,
-        images_directory_path: Optional[str] = None,
-        annotations_directory_path: Optional[str] = None,
+        images_directory_path: str | None = None,
+        annotations_directory_path: str | None = None,
         min_image_area_percentage: float = 0.0,
         max_image_area_percentage: float = 1.0,
         approximation_percentage: float = 0.0,
@@ -507,9 +474,9 @@ class DetectionDataset(BaseDataset):
 
     def as_yolo(
         self,
-        images_directory_path: Optional[str] = None,
-        annotations_directory_path: Optional[str] = None,
-        data_yaml_path: Optional[str] = None,
+        images_directory_path: str | None = None,
+        annotations_directory_path: str | None = None,
+        data_yaml_path: str | None = None,
         min_image_area_percentage: float = 0.0,
         max_image_area_percentage: float = 1.0,
         approximation_percentage: float = 0.0,
@@ -574,7 +541,6 @@ class DetectionDataset(BaseDataset):
             force_masks (bool): If True,
                 forces masks to be loaded for all annotations,
                 regardless of whether they are present.
-
         Returns:
             DetectionDataset: A DetectionDataset instance containing
                 the loaded images and annotations.
@@ -609,8 +575,8 @@ class DetectionDataset(BaseDataset):
 
     def as_coco(
         self,
-        images_directory_path: Optional[str] = None,
-        annotations_path: Optional[str] = None,
+        images_directory_path: str | None = None,
+        annotations_path: str | None = None,
         min_image_area_percentage: float = 0.0,
         max_image_area_percentage: float = 1.0,
         approximation_percentage: float = 0.0,
@@ -681,9 +647,9 @@ class ClassificationDataset(BaseDataset):
 
     def __init__(
         self,
-        classes: List[str],
-        images: Union[List[str], Dict[str, np.ndarray]],
-        annotations: Dict[str, Classifications],
+        classes: list[str],
+        images: list[str] | dict[str, np.ndarray],
+        annotations: dict[str, Classifications],
     ) -> None:
         self.classes = classes
 
@@ -696,7 +662,7 @@ class ClassificationDataset(BaseDataset):
         # Eliminate duplicates while preserving order
         self.image_paths = list(dict.fromkeys(images))
 
-        self._images_in_memory: Dict[str, np.ndarray] = {}
+        self._images_in_memory: dict[str, np.ndarray] = {}
         if isinstance(images, dict):
             self._images_in_memory = images
             warn_deprecated(
@@ -705,28 +671,6 @@ class ClassificationDataset(BaseDataset):
                 "a list of paths `List[str]` instead."
             )
 
-    @property
-    @deprecated(
-        "`DetectionDataset.images` property is deprecated and will be removed in "
-        "`supervision-0.26.0`. Iterate with `for path, image, annotation in dataset:` "
-        "instead."
-    )
-    def images(self) -> Dict[str, np.ndarray]:
-        """
-        Load all images to memory and return them as a dictionary.
-
-        !!! warning
-
-            Only use this when you need all images at once.
-            It is much more memory-efficient to initialize dataset with
-            image paths and use `for path, image, annotation in dataset:`.
-        """
-        if self._images_in_memory:
-            return self._images_in_memory
-
-        images = {image_path: cv2.imread(image_path) for image_path in self.image_paths}
-        return images
-
     def _get_image(self, image_path: str) -> np.ndarray:
         """Assumes that image is in dataset"""
         if self._images_in_memory:
@@ -736,7 +680,7 @@ class ClassificationDataset(BaseDataset):
     def __len__(self) -> int:
         return len(self._images_in_memory) or len(self.image_paths)
 
-    def __getitem__(self, i: int) -> Tuple[str, np.ndarray, Classifications]:
+    def __getitem__(self, i: int) -> tuple[str, np.ndarray, Classifications]:
         """
         Returns:
             Tuple[str, np.ndarray, Classifications]: The image path, image data,
@@ -747,7 +691,7 @@ class ClassificationDataset(BaseDataset):
         annotation = self.annotations[image_path]
         return image_path, image, annotation
 
-    def __iter__(self) -> Iterator[Tuple[str, np.ndarray, Classifications]]:
+    def __iter__(self) -> Iterator[tuple[str, np.ndarray, Classifications]]:
         """
         Iterate over the images and annotations in the dataset.
 
@@ -785,9 +729,9 @@ class ClassificationDataset(BaseDataset):
     def split(
         self,
         split_ratio: float = 0.8,
-        random_state: Optional[int] = None,
+        random_state: int | None = None,
         shuffle: bool = True,
-    ) -> Tuple[ClassificationDataset, ClassificationDataset]:
+    ) -> tuple[ClassificationDataset, ClassificationDataset]:
         """
         Splits the dataset into two parts (training and testing)
             using the provided split_ratio.
@@ -820,8 +764,8 @@ class ClassificationDataset(BaseDataset):
             shuffle=shuffle,
         )
 
-        train_input: Union[List[str], Dict[str, np.ndarray]]
-        test_input: Union[List[str], Dict[str, np.ndarray]]
+        train_input: list[str] | dict[str, np.ndarray]
+        test_input: list[str] | dict[str, np.ndarray]
         if self._images_in_memory:
             train_input = {path: self._images_in_memory[path] for path in train_paths}
             test_input = {path: self._images_in_memory[path] for path in test_paths}

supervision/dataset/formats/coco.py

@@ -1,7 +1,7 @@
 import os
 from datetime import datetime
 from pathlib import Path
-from typing import TYPE_CHECKING, Dict, List, Tuple
+from typing import TYPE_CHECKING
 
 import numpy as np
 import numpy.typing as npt
@@ -13,18 +13,15 @@ from supervision.dataset.utils import (
     rle_to_mask,
 )
 from supervision.detection.core import Detections
-from supervision.detection.utils import (
-    contains_holes,
-    contains_multiple_segments,
-    polygon_to_mask,
-)
+from supervision.detection.utils.converters import polygon_to_mask
+from supervision.detection.utils.masks import contains_holes, contains_multiple_segments
 from supervision.utils.file import read_json_file, save_json_file
 
 if TYPE_CHECKING:
     from supervision.dataset.core import DetectionDataset
 
 
-def coco_categories_to_classes(coco_categories: List[dict]) -> List[str]:
+def coco_categories_to_classes(coco_categories: list[dict]) -> list[str]:
     return [
         category["name"]
         for category in sorted(coco_categories, key=lambda category: category["id"])
@@ -32,8 +29,8 @@ def coco_categories_to_classes(coco_categories: List[dict]) -> List[str]:
 
 
 def build_coco_class_index_mapping(
-    coco_categories: List[dict], target_classes: List[str]
-) -> Dict[int, int]:
+    coco_categories: list[dict], target_classes: list[str]
+) -> dict[int, int]:
     source_class_to_index = {
         category["name"]: category["id"] for category in coco_categories
     }
@@ -43,7 +40,7 @@ def build_coco_class_index_mapping(
     }
 
 
-def classes_to_coco_categories(classes: List[str]) -> List[dict]:
+def classes_to_coco_categories(classes: list[str]) -> list[dict]:
     return [
         {
             "id": class_id,
@@ -55,8 +52,8 @@ def classes_to_coco_categories(classes: List[str]) -> List[dict]:
 
 
 def group_coco_annotations_by_image_id(
-    coco_annotations: List[dict],
-) -> Dict[int, List[dict]]:
+    coco_annotations: list[dict],
+) -> dict[int, list[dict]]:
     annotations = {}
     for annotation in coco_annotations:
         image_id = annotation["image_id"]
@@ -67,7 +64,7 @@ def group_coco_annotations_by_image_id(
 
 
 def coco_annotations_to_masks(
-    image_annotations: List[dict], resolution_wh: Tuple[int, int]
+    image_annotations: list[dict], resolution_wh: tuple[int, int]
 ) -> npt.NDArray[np.bool_]:
     return np.array(
         [
@@ -90,7 +87,10 @@ def coco_annotations_to_masks(
 
 
 def coco_annotations_to_detections(
-    image_annotations: List[dict], resolution_wh: Tuple[int, int], with_masks: bool
+    image_annotations: list[dict],
+    resolution_wh: tuple[int, int],
+    with_masks: bool,
+    use_iscrowd: bool = True,
 ) -> Detections:
     if not image_annotations:
         return Detections.empty()
@@ -102,15 +102,26 @@ def coco_annotations_to_detections(
     xyxy = np.asarray(xyxy)
     xyxy[:, 2:4] += xyxy[:, 0:2]
 
+    data = dict()
+    if use_iscrowd:
+        iscrowd = [
+            image_annotation["iscrowd"] for image_annotation in image_annotations
+        ]
+        area = [image_annotation["area"] for image_annotation in image_annotations]
+        data = dict(
+            iscrowd=np.asarray(iscrowd, dtype=int), area=np.asarray(area, dtype=float)
+        )
+
     if with_masks:
         mask = coco_annotations_to_masks(
             image_annotations=image_annotations, resolution_wh=resolution_wh
         )
-        return Detections(
-            class_id=np.asarray(class_ids, dtype=int), xyxy=xyxy, mask=mask
-        )
+    else:
+        mask = None
 
-    return Detections(xyxy=xyxy, class_id=np.asarray(class_ids, dtype=int))
+    return Detections(
+        class_id=np.asarray(class_ids, dtype=int), xyxy=xyxy, mask=mask, data=data
+    )
 
 
 def detections_to_coco_annotations(
@@ -120,7 +131,7 @@ def detections_to_coco_annotations(
     min_image_area_percentage: float = 0.0,
     max_image_area_percentage: float = 1.0,
     approximation_percentage: float = 0.75,
-) -> Tuple[List[Dict], int]:
+) -> tuple[list[dict], int]:
     coco_annotations = []
     for xyxy, mask, _, class_id, _, _ in detections:
         box_width, box_height = xyxy[2] - xyxy[0], xyxy[3] - xyxy[1]
@@ -159,16 +170,58 @@ def detections_to_coco_annotations(
     return coco_annotations, annotation_id
 
 
+def get_coco_class_index_mapping(annotations_path: str) -> dict[int, int]:
+    """
+    Generates a mapping from sequential class indices to original COCO class ids.
+
+    This function is essential when working with models that expect class ids to be
+    zero-indexed and sequential (0 to 79), as opposed to the original COCO
+    dataset where category ids are non-contiguous ranging from 1 to 90 but skipping some
+    ids.
+
+    Use Cases:
+        - Evaluating models trained with COCO-style annotations where class ids
+          are sequential ranging from 0 to 79.
+        - Ensuring consistent class indexing across training, inference and evaluation,
+          when using different tools or datasets with COCO format.
+        - Reproducing results from models that assume sequential class ids (0 to 79).
+
+    How it Works:
+        - Reads the COCO annotation file in its original format (`annotations_path`).
+        - Extracts and sorts all class names by their original COCO id (1 to 90).
+        - Builds a mapping from COCO class ids (not sequential with skipped ids) to
+          new class ids (sequential ranging from 0 to 79).
+        - Returns a dictionary mapping: `{new_class_id: original_COCO_class_id}`.
+
+    Args:
+        annotations_path (str): Path to COCO JSON annotations file
+        (e.g., `instances_val2017.json`).
+
+    Returns:
+        Dict[int, int]: A mapping from new class id (sequential ranging from 0 to 79)
+        to original COCO class id (1 to 90 with skipped ids).
+    """
+    coco_data = read_json_file(annotations_path)
+    classes = coco_categories_to_classes(coco_categories=coco_data["categories"])
+    class_mapping = build_coco_class_index_mapping(
+        coco_categories=coco_data["categories"], target_classes=classes
+    )
+    return {v: k for k, v in class_mapping.items()}
+
+
 def load_coco_annotations(
     images_directory_path: str,
     annotations_path: str,
     force_masks: bool = False,
-) -> Tuple[List[str], List[str], Dict[str, Detections]]:
+    use_iscrowd: bool = True,
+) -> tuple[list[str], list[str], dict[str, Detections]]:
     coco_data = read_json_file(file_path=annotations_path)
     classes = coco_categories_to_classes(coco_categories=coco_data["categories"])
+
     class_index_mapping = build_coco_class_index_mapping(
         coco_categories=coco_data["categories"], target_classes=classes
     )
+
     coco_images = coco_data["images"]
     coco_annotations_groups = group_coco_annotations_by_image_id(
         coco_annotations=coco_data["annotations"]
@@ -190,7 +243,9 @@ def load_coco_annotations(
             image_annotations=image_annotations,
             resolution_wh=(image_width, image_height),
             with_masks=force_masks,
+            use_iscrowd=use_iscrowd,
         )
+
         annotation = map_detections_class_id(
             source_to_target_mapping=class_index_mapping,
             detections=annotation,

supervision/dataset/formats/pascal_voc.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 import os
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
 from xml.etree.ElementTree import Element, SubElement
 
 import cv2
@@ -10,12 +11,12 @@ from defusedxml.minidom import parseString
 
 from supervision.dataset.utils import approximate_mask_with_polygons
 from supervision.detection.core import Detections
-from supervision.detection.utils import polygon_to_mask, polygon_to_xyxy
+from supervision.detection.utils.converters import polygon_to_mask, polygon_to_xyxy
 from supervision.utils.file import list_files_with_extensions
 
 
 def object_to_pascal_voc(
-    xyxy: np.ndarray, name: str, polygon: Optional[np.ndarray] = None
+    xyxy: np.ndarray, name: str, polygon: np.ndarray | None = None
 ) -> Element:
     root = Element("object")
 
@@ -51,9 +52,9 @@ def object_to_pascal_voc(
 
 def detections_to_pascal_voc(
     detections: Detections,
-    classes: List[str],
+    classes: list[str],
     filename: str,
-    image_shape: Tuple[int, int, int],
+    image_shape: tuple[int, int, int],
     min_image_area_percentage: float = 0.0,
     max_image_area_percentage: float = 1.0,
     approximation_percentage: float = 0.75,
@@ -138,7 +139,7 @@ def load_pascal_voc_annotations(
     images_directory_path: str,
     annotations_directory_path: str,
     force_masks: bool = False,
-) -> Tuple[List[str], List[str], Dict[str, Detections]]:
+) -> tuple[list[str], list[str], dict[str, Detections]]:
     """
     Loads PASCAL VOC XML annotations and returns the image name,
         a Detections instance, and a list of class names.
@@ -163,7 +164,7 @@ def load_pascal_voc_annotations(
         )
     ]
 
-    classes: List[str] = []
+    classes: list[str] = []
     annotations = {}
 
     for image_path in image_paths:
@@ -187,8 +188,8 @@ def load_pascal_voc_annotations(
 
 
 def detections_from_xml_obj(
-    root: Element, classes: List[str], resolution_wh, force_masks: bool = False
-) -> Tuple[Detections, List[str]]:
+    root: Element, classes: list[str], resolution_wh, force_masks: bool = False
+) -> tuple[Detections, list[str]]:
     """
     Converts an XML object in Pascal VOC format to a Detections object.
     Expected XML format:

supervision/dataset/formats/yolo.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 import os
 from pathlib import Path
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING
 
 import numpy as np
 from PIL import Image
@@ -8,7 +10,7 @@ from PIL import Image
 from supervision.config import ORIENTED_BOX_COORDINATES
 from supervision.dataset.utils import approximate_mask_with_polygons
 from supervision.detection.core import Detections
-from supervision.detection.utils import polygon_to_mask, polygon_to_xyxy
+from supervision.detection.utils.converters import polygon_to_mask, polygon_to_xyxy
 from supervision.utils.file import (
     list_files_with_extensions,
     read_txt_file,
@@ -21,7 +23,7 @@ if TYPE_CHECKING:
     from supervision.dataset.core import DetectionDataset
 
 
-def _parse_box(values: List[str]) -> np.ndarray:
+def _parse_box(values: list[str]) -> np.ndarray:
     x_center, y_center, width, height = values
     return np.array(
         [
@@ -40,12 +42,12 @@ def _box_to_polygon(box: np.ndarray) -> np.ndarray:
     )
 
 
-def _parse_polygon(values: List[str]) -> np.ndarray:
+def _parse_polygon(values: list[str]) -> np.ndarray:
     return np.array(values, dtype=np.float32).reshape(-1, 2)
 
 
 def _polygons_to_masks(
-    polygons: List[np.ndarray], resolution_wh: Tuple[int, int]
+    polygons: list[np.ndarray], resolution_wh: tuple[int, int]
 ) -> np.ndarray:
     return np.array(
         [
@@ -56,11 +58,11 @@ def _polygons_to_masks(
     )
 
 
-def _with_mask(lines: List[str]) -> bool:
+def _with_mask(lines: list[str]) -> bool:
     return any([len(line.split()) > 5 for line in lines])
 
 
-def _extract_class_names(file_path: str) -> List[str]:
+def _extract_class_names(file_path: str) -> list[str]:
     data = read_yaml_file(file_path=file_path)
     names = data["names"]
     if isinstance(names, dict):
@@ -74,8 +76,8 @@ def _image_name_to_annotation_name(image_name: str) -> str:
 
 
 def yolo_annotations_to_detections(
-    lines: List[str],
-    resolution_wh: Tuple[int, int],
+    lines: list[str],
+    resolution_wh: tuple[int, int],
     with_masks: bool,
     is_obb: bool = False,
 ) -> Detections:
@@ -127,7 +129,7 @@ def load_yolo_annotations(
     data_yaml_path: str,
     force_masks: bool = False,
     is_obb: bool = False,
-) -> Tuple[List[str], List[str], Dict[str, Detections]]:
+) -> tuple[list[str], list[str], dict[str, Detections]]:
     """
     Loads YOLO annotations and returns class names, images,
         and their corresponding detections.
@@ -204,8 +206,8 @@ def load_yolo_annotations(
 def object_to_yolo(
     xyxy: np.ndarray,
     class_id: int,
-    image_shape: Tuple[int, int, int],
-    polygon: Optional[np.ndarray] = None,
+    image_shape: tuple[int, int, int],
+    polygon: np.ndarray | None = None,
 ) -> str:
     h, w, _ = image_shape
     if polygon is None:
@@ -225,11 +227,11 @@ def object_to_yolo(
 
 def detections_to_yolo_annotations(
     detections: Detections,
-    image_shape: Tuple[int, int, int],
+    image_shape: tuple[int, int, int],
     min_image_area_percentage: float = 0.0,
     max_image_area_percentage: float = 1.0,
     approximation_percentage: float = 0.75,
-) -> List[str]:
+) -> list[str]:
     annotation = []
     for xyxy, mask, _, class_id, _, _ in detections:
         if class_id is None:
@@ -260,7 +262,7 @@ def detections_to_yolo_annotations(
 
 
 def save_yolo_annotations(
-    dataset: "DetectionDataset",
+    dataset: DetectionDataset,
     annotations_directory_path: str,
     min_image_area_percentage: float = 0.0,
     max_image_area_percentage: float = 1.0,
@@ -283,7 +285,7 @@ def save_yolo_annotations(
         save_text_file(lines=lines, file_path=yolo_annotations_path)
 
 
-def save_data_yaml(data_yaml_path: str, classes: List[str]) -> None:
+def save_data_yaml(data_yaml_path: str, classes: list[str]) -> None:
     data = {"nc": len(classes), "names": classes}
     Path(data_yaml_path).parent.mkdir(parents=True, exist_ok=True)
     save_yaml_file(data=data, file_path=data_yaml_path)

supervision/dataset/utils.py

@@ -1,19 +1,21 @@
+from __future__ import annotations
+
 import copy
 import os
 import random
 import shutil
 from pathlib import Path
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, TypeVar, Union
+from typing import TYPE_CHECKING, TypeVar
 
 import cv2
 import numpy as np
 import numpy.typing as npt
 
 from supervision.detection.core import Detections
-from supervision.detection.utils import (
+from supervision.detection.utils.converters import mask_to_polygons
+from supervision.detection.utils.polygons import (
     approximate_polygon,
     filter_polygons_by_area,
-    mask_to_polygons,
 )
 
 if TYPE_CHECKING:
@@ -27,7 +29,7 @@ def approximate_mask_with_polygons(
     min_image_area_percentage: float = 0.0,
     max_image_area_percentage: float = 1.0,
     approximation_percentage: float = 0.75,
-) -> List[np.ndarray]:
+) -> list[np.ndarray]:
     height, width = mask.shape
     image_area = height * width
     minimum_detection_area = min_image_area_percentage * image_area
@@ -50,7 +52,7 @@ def approximate_mask_with_polygons(
     ]
 
 
-def merge_class_lists(class_lists: List[List[str]]) -> List[str]:
+def merge_class_lists(class_lists: list[list[str]]) -> list[str]:
     unique_classes = set()
 
     for class_list in class_lists:
@@ -61,8 +63,8 @@ def merge_class_lists(class_lists: List[List[str]]) -> List[str]:
 
 
 def build_class_index_mapping(
-    source_classes: List[str], target_classes: List[str]
-) -> Dict[int, int]:
+    source_classes: list[str], target_classes: list[str]
+) -> dict[int, int]:
     """Returns the index map of source classes -> target classes."""
     index_mapping = {}
 
@@ -79,7 +81,7 @@ def build_class_index_mapping(
 
 
 def map_detections_class_id(
-    source_to_target_mapping: Dict[int, int], detections: Detections
+    source_to_target_mapping: dict[int, int], detections: Detections
 ) -> Detections:
     if detections.class_id is None:
         raise ValueError("Detections must have class_id attribute.")
@@ -98,9 +100,7 @@ def map_detections_class_id(
     return detections_copy
 
 
-def save_dataset_images(
-    dataset: "DetectionDataset", images_directory_path: str
-) -> None:
+def save_dataset_images(dataset: DetectionDataset, images_directory_path: str) -> None:
     Path(images_directory_path).mkdir(parents=True, exist_ok=True)
     for image_path in dataset.image_paths:
         final_path = os.path.join(images_directory_path, Path(image_path).name)
@@ -112,11 +112,11 @@ def save_dataset_images(
 
 
 def train_test_split(
-    data: List[T],
+    data: list[T],
     train_ratio: float = 0.8,
-    random_state: Optional[int] = None,
+    random_state: int | None = None,
     shuffle: bool = True,
-) -> Tuple[List[T], List[T]]:
+) -> tuple[list[T], list[T]]:
     """
     Splits the data into two parts using the provided train_ratio.
 
@@ -140,7 +140,7 @@ def train_test_split(
 
 
 def rle_to_mask(
-    rle: Union[npt.NDArray[np.int_], List[int]], resolution_wh: Tuple[int, int]
+    rle: npt.NDArray[np.int_] | list[int], resolution_wh: tuple[int, int]
 ) -> npt.NDArray[np.bool_]:
     """
     Converts run-length encoding (RLE) to a binary mask.
@@ -195,7 +195,7 @@ def rle_to_mask(
     return decoded_rle.reshape((height, width), order="F")
 
 
-def mask_to_rle(mask: npt.NDArray[np.bool_]) -> List[int]:
+def mask_to_rle(mask: npt.NDArray[np.bool_]) -> list[int]:
     """
     Converts a binary mask into a run-length encoding (RLE).
 

supervision/detection/line_zone.py

@@ -1,8 +1,11 @@
+from __future__ import annotations
+
 import math
 import warnings
 from collections import Counter, defaultdict, deque
+from collections.abc import Iterable
 from functools import lru_cache
-from typing import Any, Deque, Dict, Iterable, List, Literal, Optional, Tuple
+from typing import Any, Literal
 
 import cv2
 import numpy as np
@@ -10,7 +13,7 @@ import numpy.typing as npt
 
 from supervision.config import CLASS_NAME_DATA_FIELD
 from supervision.detection.core import Detections
-from supervision.detection.utils import cross_product
+from supervision.detection.utils.internal import cross_product
 from supervision.draw.color import Color
 from supervision.draw.utils import draw_rectangle, draw_text
 from supervision.geometry.core import Point, Position, Rect, Vector
@@ -99,7 +102,7 @@ class LineZone:
         self.vector = Vector(start=start, end=end)
         self.limits = self._calculate_region_of_interest_limits(vector=self.vector)
         self.crossing_history_length = max(2, minimum_crossing_threshold + 1)
-        self.crossing_state_history: Dict[int, Deque[bool]] = defaultdict(
+        self.crossing_state_history: dict[int, deque[bool]] = defaultdict(
             lambda: deque(maxlen=self.crossing_history_length)
         )
         self._in_count_per_class: Counter = Counter()
@@ -107,7 +110,7 @@ class LineZone:
         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] = {}
+        self.class_id_to_name: dict[int, str] = {}
 
     @property
     def in_count(self) -> int:
@@ -118,14 +121,14 @@ class LineZone:
         return sum(self._out_count_per_class.values())
 
     @property
-    def in_count_per_class(self) -> Dict[int, int]:
+    def in_count_per_class(self) -> dict[int, int]:
         return dict(self._in_count_per_class)
 
     @property
-    def out_count_per_class(self) -> Dict[int, int]:
+    def out_count_per_class(self) -> dict[int, int]:
         return dict(self._out_count_per_class)
 
-    def trigger(self, detections: Detections) -> Tuple[np.ndarray, np.ndarray]:
+    def trigger(self, detections: Detections) -> tuple[np.ndarray, np.ndarray]:
         """
         Update the `in_count` and `out_count` based on the objects that cross the line.
 
@@ -160,7 +163,7 @@ class LineZone:
             self._compute_anchor_sides(detections)
         )
 
-        class_ids: List[Optional[int]] = (
+        class_ids: list[int | None] = (
             list(detections.class_id)
             if detections.class_id is not None
             else [None] * len(detections)
@@ -200,7 +203,7 @@ class LineZone:
         return crossed_in, crossed_out
 
     @staticmethod
-    def _calculate_region_of_interest_limits(vector: Vector) -> Tuple[Vector, Vector]:
+    def _calculate_region_of_interest_limits(vector: Vector) -> tuple[Vector, Vector]:
         magnitude = vector.magnitude
 
         if magnitude == 0:
@@ -233,7 +236,7 @@ class LineZone:
 
     def _compute_anchor_sides(
         self, detections: Detections
-    ) -> Tuple[npt.NDArray[np.bool_], npt.NDArray[np.bool_], npt.NDArray[np.bool_]]:
+    ) -> tuple[npt.NDArray[np.bool_], npt.NDArray[np.bool_], npt.NDArray[np.bool_]]:
         """
         Find if detections' anchors are within the limit of the line
         zone and which anchors are on its left and right side.
@@ -324,8 +327,8 @@ class LineZoneAnnotator:
         text_scale: float = 0.5,
         text_offset: float = 1.5,
         text_padding: int = 10,
-        custom_in_text: Optional[str] = None,
-        custom_out_text: Optional[str] = None,
+        custom_in_text: str | None = None,
+        custom_out_text: str | None = None,
         display_in_count: bool = True,
         display_out_count: bool = True,
         display_text_box: bool = True,
@@ -471,7 +474,7 @@ class LineZoneAnnotator:
         text_height: int,
         is_in_count: bool,
         label_dimension: int,
-    ) -> Tuple[int, int]:
+    ) -> tuple[int, int]:
         """
         Calculate insertion anchor in frame to position the center of the count image.
 
@@ -663,7 +666,7 @@ class LineZoneAnnotator:
         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_args: dict[str, Any] = dict(
             text=text,
             text_anchor=annotation_center,
             text_scale=text_scale,
@@ -756,8 +759,8 @@ class LineZoneAnnotatorMulticlass:
     def annotate(
         self,
         frame: np.ndarray,
-        line_zones: List[LineZone],
-        line_zone_labels: Optional[List[str]] = None,
+        line_zones: list[LineZone],
+        line_zone_labels: list[str] | None = None,
     ) -> np.ndarray:
         """
         Draws a table with the number of objects of each class that crossed each line.

supervision/detection/lmm.py

@@ -1,184 +0,0 @@
-import re
-from enum import Enum
-from typing import Any, Dict, List, Optional, Tuple, Union
-
-import numpy as np
-
-from supervision.detection.utils import polygon_to_mask, polygon_to_xyxy
-
-
-class LMM(Enum):
-    PALIGEMMA = "paligemma"
-    FLORENCE_2 = "florence_2"
-
-
-RESULT_TYPES: Dict[LMM, type] = {LMM.PALIGEMMA: str, LMM.FLORENCE_2: dict}
-
-REQUIRED_ARGUMENTS: Dict[LMM, List[str]] = {
-    LMM.PALIGEMMA: ["resolution_wh"],
-    LMM.FLORENCE_2: ["resolution_wh"],
-}
-
-ALLOWED_ARGUMENTS: Dict[LMM, List[str]] = {
-    LMM.PALIGEMMA: ["resolution_wh", "classes"],
-    LMM.FLORENCE_2: ["resolution_wh"],
-}
-
-SUPPORTED_TASKS_FLORENCE_2 = [
-    "<OD>",
-    "<CAPTION_TO_PHRASE_GROUNDING>",
-    "<DENSE_REGION_CAPTION>",
-    "<REGION_PROPOSAL>",
-    "<OCR_WITH_REGION>",
-    "<REFERRING_EXPRESSION_SEGMENTATION>",
-    "<REGION_TO_SEGMENTATION>",
-    "<OPEN_VOCABULARY_DETECTION>",
-    "<REGION_TO_CATEGORY>",
-    "<REGION_TO_DESCRIPTION>",
-]
-
-
-def validate_lmm_parameters(
-    lmm: Union[LMM, str], result: Any, kwargs: Dict[str, Any]
-) -> LMM:
-    if isinstance(lmm, str):
-        try:
-            lmm = LMM(lmm.lower())
-        except ValueError:
-            raise ValueError(
-                f"Invalid lmm value: {lmm}. Must be one of {[e.value for e in LMM]}"
-            )
-
-    if not isinstance(result, RESULT_TYPES[lmm]):
-        raise ValueError(
-            f"Invalid LMM result type: {type(result)}. Must be {RESULT_TYPES[lmm]}"
-        )
-
-    required_args = REQUIRED_ARGUMENTS.get(lmm, [])
-    for arg in required_args:
-        if arg not in kwargs:
-            raise ValueError(f"Missing required argument: {arg}")
-
-    allowed_args = ALLOWED_ARGUMENTS.get(lmm, [])
-    for arg in kwargs:
-        if arg not in allowed_args:
-            raise ValueError(f"Argument {arg} is not allowed for {lmm.name}")
-
-    return lmm
-
-
-def from_paligemma(
-    result: str, resolution_wh: Tuple[int, int], classes: Optional[List[str]] = None
-) -> Tuple[np.ndarray, Optional[np.ndarray], np.ndarray]:
-    w, h = resolution_wh
-    pattern = re.compile(
-        r"(?<!<loc\d{4}>)<loc(\d{4})><loc(\d{4})><loc(\d{4})><loc(\d{4})> ([\w\s\-]+)"
-    )
-    matches = pattern.findall(result)
-    matches = np.array(matches) if matches else np.empty((0, 5))
-
-    xyxy, class_name = matches[:, [1, 0, 3, 2]], matches[:, 4]
-    xyxy = xyxy.astype(int) / 1024 * np.array([w, h, w, h])
-    class_name = np.char.strip(class_name.astype(str))
-    class_id = None
-
-    if classes is not None:
-        mask = np.array([name in classes for name in class_name]).astype(bool)
-        xyxy, class_name = xyxy[mask], class_name[mask]
-        class_id = np.array([classes.index(name) for name in class_name])
-
-    return xyxy, class_id, class_name
-
-
-def from_florence_2(
-    result: dict, resolution_wh: Tuple[int, int]
-) -> Tuple[
-    np.ndarray, Optional[np.ndarray], Optional[np.ndarray], Optional[np.ndarray]
-]:
-    """
-    Parse results from the Florence 2 multi-model model.
-    https://huggingface.co/microsoft/Florence-2-large
-
-    Parameters:
-        result: dict containing the model output
-
-    Returns:
-        xyxy (np.ndarray): An array of shape `(n, 4)` containing
-            the bounding boxes coordinates in format `[x1, y1, x2, y2]`
-        labels: (Optional[np.ndarray]): An array of shape `(n,)` containing
-            the class labels for each bounding box
-        masks: (Optional[np.ndarray]): An array of shape `(n, h, w)` containing
-            the segmentation masks for each bounding box
-        obb_boxes: (Optional[np.ndarray]): An array of shape `(n, 4, 2)` containing
-            oriented bounding boxes.
-    """
-    assert len(result) == 1, f"Expected result with a single element. Got: {result}"
-    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}"
-        )
-    result = result[task]
-
-    if task in ["<OD>", "<CAPTION_TO_PHRASE_GROUNDING>", "<DENSE_REGION_CAPTION>"]:
-        xyxy = np.array(result["bboxes"], dtype=np.float32)
-        labels = np.array(result["labels"])
-        return xyxy, labels, None, None
-
-    if task == "<REGION_PROPOSAL>":
-        xyxy = np.array(result["bboxes"], dtype=np.float32)
-        # provides labels, but they are ["", "", "", ...]
-        return xyxy, None, None, None
-
-    if task == "<OCR_WITH_REGION>":
-        xyxyxyxy = np.array(result["quad_boxes"], dtype=np.float32)
-        xyxyxyxy = xyxyxyxy.reshape(-1, 4, 2)
-        xyxy = np.array([polygon_to_xyxy(polygon) for polygon in xyxyxyxy])
-        labels = np.array(result["labels"])
-        return xyxy, labels, None, xyxyxyxy
-
-    if task in ["<REFERRING_EXPRESSION_SEGMENTATION>", "<REGION_TO_SEGMENTATION>"]:
-        xyxy_list = []
-        masks_list = []
-        for polygons_of_same_class in result["polygons"]:
-            for polygon in polygons_of_same_class:
-                polygon = np.reshape(polygon, (-1, 2)).astype(np.int32)
-                mask = polygon_to_mask(polygon, resolution_wh).astype(bool)
-                masks_list.append(mask)
-                xyxy = polygon_to_xyxy(polygon)
-                xyxy_list.append(xyxy)
-            # per-class labels also provided, but they are ["", "", "", ...]
-            # when we figure out how to set class names, we can do
-            # zip(result["labels"], result["polygons"])
-        xyxy = np.array(xyxy_list, dtype=np.float32)
-        masks = np.array(masks_list)
-        return xyxy, None, masks, None
-
-    if task == "<OPEN_VOCABULARY_DETECTION>":
-        xyxy = np.array(result["bboxes"], dtype=np.float32)
-        labels = np.array(result["bboxes_labels"])
-        # Also has "polygons" and "polygons_labels", but they don't seem to be used
-        return xyxy, labels, None, None
-
-    if task in ["<REGION_TO_CATEGORY>", "<REGION_TO_DESCRIPTION>"]:
-        assert isinstance(
-            result, str
-        ), f"Expected string as <REGION_TO_CATEGORY> result, got {type(result)}"
-
-        if result == "No object detected.":
-            return np.empty((0, 4), dtype=np.float32), np.array([]), None, None
-
-        pattern = re.compile(r"<loc_(\d+)><loc_(\d+)><loc_(\d+)><loc_(\d+)>")
-        match = pattern.search(result)
-        assert (
-            match is not None
-        ), f"Expected string to end in location tags, but got {result}"
-
-        w, h = resolution_wh
-        xyxy = np.array([match.groups()], dtype=np.float32)
-        xyxy *= np.array([w, h, w, h]) / 1000
-        result_string = result[: match.start()]
-        labels = np.array([result_string])
-        return xyxy, labels, None, None
-
-    assert False, f"Unimplemented task: {task}"

supervision/detection/overlap_filter.py

@@ -1,270 +0,0 @@
-from __future__ import annotations
-
-from enum import Enum
-from typing import List, Union
-
-import numpy as np
-import numpy.typing as npt
-
-from supervision.detection.utils import box_iou_batch, mask_iou_batch
-
-
-def resize_masks(masks: np.ndarray, max_dimension: int = 640) -> np.ndarray:
-    """
-    Resize all masks in the array to have a maximum dimension of max_dimension,
-    maintaining aspect ratio.
-
-    Args:
-        masks (np.ndarray): 3D array of binary masks with shape (N, H, W).
-        max_dimension (int): The maximum dimension for the resized masks.
-
-    Returns:
-        np.ndarray: Array of resized masks.
-    """
-    max_height = np.max(masks.shape[1])
-    max_width = np.max(masks.shape[2])
-    scale = min(max_dimension / max_height, max_dimension / max_width)
-
-    new_height = int(scale * max_height)
-    new_width = int(scale * max_width)
-
-    x = np.linspace(0, max_width - 1, new_width).astype(int)
-    y = np.linspace(0, max_height - 1, new_height).astype(int)
-    xv, yv = np.meshgrid(x, y)
-
-    resized_masks = masks[:, yv, xv]
-
-    resized_masks = resized_masks.reshape(masks.shape[0], new_height, new_width)
-    return resized_masks
-
-
-def mask_non_max_suppression(
-    predictions: np.ndarray,
-    masks: np.ndarray,
-    iou_threshold: float = 0.5,
-    mask_dimension: int = 640,
-) -> np.ndarray:
-    """
-    Perform Non-Maximum Suppression (NMS) on segmentation predictions.
-
-    Args:
-        predictions (np.ndarray): A 2D 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)`. Shape: `(N, 5)` or
-            `(N, 6)`, where N is the number of predictions.
-        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): The intersection-over-union threshold
-            to use for non-maximum suppression.
-        mask_dimension (int): The dimension to which the masks should be
-            resized before computing IOU values. Defaults to 640.
-
-    Returns:
-        np.ndarray: A boolean array indicating which predictions to keep after
-            non-maximum suppression.
-
-    Raises:
-        AssertionError: If `iou_threshold` is not within the closed
-            range from `0` to `1`.
-    """
-    assert 0 <= iou_threshold <= 1, (
-        "Value of `iou_threshold` must be in the closed range from 0 to 1, "
-        f"{iou_threshold} given."
-    )
-    rows, columns = predictions.shape
-
-    if columns == 5:
-        predictions = np.c_[predictions, np.zeros(rows)]
-
-    sort_index = predictions[:, 4].argsort()[::-1]
-    predictions = predictions[sort_index]
-    masks = masks[sort_index]
-    masks_resized = resize_masks(masks, mask_dimension)
-    ious = mask_iou_batch(masks_resized, masks_resized)
-    categories = predictions[:, 5]
-
-    keep = np.ones(rows, dtype=bool)
-    for i in range(rows):
-        if keep[i]:
-            condition = (ious[i] > iou_threshold) & (categories[i] == categories)
-            keep[i + 1 :] = np.where(condition[i + 1 :], False, keep[i + 1 :])
-
-    return keep[sort_index.argsort()]
-
-
-def box_non_max_suppression(
-    predictions: np.ndarray, iou_threshold: float = 0.5
-) -> np.ndarray:
-    """
-    Perform Non-Maximum Suppression (NMS) on object detection predictions.
-
-    Args:
-        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): The intersection-over-union threshold
-            to use for non-maximum suppression.
-
-    Returns:
-        np.ndarray: A boolean array indicating which predictions to keep after n
-            on-maximum suppression.
-
-    Raises:
-        AssertionError: If `iou_threshold` is not within the
-            closed range from `0` to `1`.
-    """
-    assert 0 <= iou_threshold <= 1, (
-        "Value of `iou_threshold` must be in the closed range from 0 to 1, "
-        f"{iou_threshold} given."
-    )
-    rows, columns = predictions.shape
-
-    # add column #5 - category filled with zeros for agnostic nms
-    if columns == 5:
-        predictions = np.c_[predictions, np.zeros(rows)]
-
-    # sort predictions column #4 - score
-    sort_index = np.flip(predictions[:, 4].argsort())
-    predictions = predictions[sort_index]
-
-    boxes = predictions[:, :4]
-    categories = predictions[:, 5]
-    ious = box_iou_batch(boxes, boxes)
-    ious = ious - np.eye(rows)
-
-    keep = np.ones(rows, dtype=bool)
-
-    for index, (iou, category) in enumerate(zip(ious, categories)):
-        if not keep[index]:
-            continue
-
-        # drop detections with iou > iou_threshold and
-        # same category as current detections
-        condition = (iou > iou_threshold) & (categories == category)
-        keep = keep & ~condition
-
-    return keep[sort_index.argsort()]
-
-
-def group_overlapping_boxes(
-    predictions: npt.NDArray[np.float64], iou_threshold: float = 0.5
-) -> List[List[int]]:
-    """
-    Apply greedy version of non-maximum merging to avoid detecting too many
-    overlapping bounding boxes for a given object.
-
-    Args:
-        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): The intersection-over-union threshold
-            to use for non-maximum suppression. Defaults to 0.5.
-
-    Returns:
-        List[List[int]]: Groups of prediction indices be merged.
-            Each group may have 1 or more elements.
-    """
-    merge_groups: List[List[int]] = []
-
-    scores = predictions[:, 4]
-    order = scores.argsort()
-
-    while len(order) > 0:
-        idx = int(order[-1])
-
-        order = order[:-1]
-        if len(order) == 0:
-            merge_groups.append([idx])
-            break
-
-        merge_candidate = np.expand_dims(predictions[idx], axis=0)
-        ious = box_iou_batch(predictions[order][:, :4], merge_candidate[:, :4])
-        ious = ious.flatten()
-
-        above_threshold = ious >= iou_threshold
-        merge_group = [idx, *np.flip(order[above_threshold]).tolist()]
-        merge_groups.append(merge_group)
-        order = order[~above_threshold]
-    return merge_groups
-
-
-def box_non_max_merge(
-    predictions: npt.NDArray[np.float64],
-    iou_threshold: float = 0.5,
-) -> List[List[int]]:
-    """
-    Apply greedy version of non-maximum merging per category to avoid detecting
-    too many overlapping bounding boxes for a given object.
-
-    Args:
-        predictions (npt.NDArray[np.float64]): An array of shape `(n, 5)` or `(n, 6)`
-            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): The intersection-over-union threshold
-            to use for non-maximum suppression. Defaults to 0.5.
-
-    Returns:
-        List[List[int]]: Groups of prediction indices be merged.
-            Each group may have 1 or more elements.
-    """
-    if predictions.shape[1] == 5:
-        return group_overlapping_boxes(predictions, iou_threshold)
-
-    category_ids = predictions[:, 5]
-    merge_groups = []
-    for category_id in np.unique(category_ids):
-        curr_indices = np.where(category_ids == category_id)[0]
-        merge_class_groups = group_overlapping_boxes(
-            predictions[curr_indices], iou_threshold
-        )
-
-        for merge_class_group in merge_class_groups:
-            merge_groups.append(curr_indices[merge_class_group].tolist())
-
-    for merge_group in merge_groups:
-        if len(merge_group) == 0:
-            raise ValueError(
-                f"Empty group detected when non-max-merging "
-                f"detections: {merge_groups}"
-            )
-    return merge_groups
-
-
-class OverlapFilter(Enum):
-    """
-    Enum specifying the strategy for filtering overlapping detections.
-
-    Attributes:
-        NONE: Do not filter detections based on overlap.
-        NON_MAX_SUPPRESSION: Filter detections using non-max suppression. This means,
-            detections that overlap by more than a set threshold will be discarded,
-            except for the one with the highest confidence.
-        NON_MAX_MERGE: Merge detections with non-max merging. This means,
-            detections that overlap by more than a set threshold will be merged
-            into a single detection.
-    """
-
-    NONE = "none"
-    NON_MAX_SUPPRESSION = "non_max_suppression"
-    NON_MAX_MERGE = "non_max_merge"
-
-    @classmethod
-    def list(cls):
-        return list(map(lambda c: c.value, cls))
-
-    @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

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import csv
 import os
-from typing import Any, Dict, List, Optional
+from typing import Any
 
 from supervision.detection.core import Detections
 
@@ -61,8 +61,8 @@ class CSVSink:
             None
         """
         self.file_name = file_name
-        self.file: Optional[open] = None
-        self.writer: Optional[csv.writer] = None
+        self.file: open | None = None
+        self.writer: csv.writer | None = None
         self.header_written = False
         self.field_names = []
 
@@ -72,9 +72,9 @@ class CSVSink:
 
     def __exit__(
         self,
-        exc_type: Optional[type],
-        exc_val: Optional[Exception],
-        exc_tb: Optional[Any],
+        exc_type: type | None,
+        exc_val: Exception | None,
+        exc_tb: Any | None,
     ) -> None:
         self.close()
 
@@ -104,8 +104,8 @@ class CSVSink:
 
     @staticmethod
     def parse_detection_data(
-        detections: Detections, custom_data: Optional[Dict[str, Any]] = None
-    ) -> List[Dict[str, Any]]:
+        detections: Detections, custom_data: dict[str, Any] | None = None
+    ) -> list[dict[str, Any]]:
         parsed_rows = []
         for i in range(len(detections.xyxy)):
             row = {
@@ -137,7 +137,7 @@ class CSVSink:
         return parsed_rows
 
     def append(
-        self, detections: Detections, custom_data: Optional[Dict[str, Any]] = None
+        self, detections: Detections, custom_data: dict[str, Any] | None = None
     ) -> None:
         """
         Append detection data to the CSV file.
@@ -173,8 +173,8 @@ class CSVSink:
 
     @staticmethod
     def parse_field_names(
-        detections: Detections, custom_data: Dict[str, Any]
-    ) -> List[str]:
+        detections: Detections, custom_data: dict[str, Any]
+    ) -> list[str]:
         dynamic_header = sorted(
             set(custom_data.keys()) | set(getattr(detections, "data", {}).keys())
         )

supervision/detection/tools/inference_slicer.py

@@ -1,13 +1,16 @@
+from __future__ import annotations
+
 import warnings
+from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor, as_completed
-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
-from supervision.detection.utils import move_boxes, move_masks, move_oriented_boxes
+from supervision.detection.utils.boxes import move_boxes, move_oriented_boxes
+from supervision.detection.utils.iou_and_nms import OverlapFilter
+from supervision.detection.utils.masks import move_masks
 from supervision.utils.image import crop_image
 from supervision.utils.internal import (
     SupervisionWarnings,
@@ -18,7 +21,7 @@ from supervision.utils.internal import (
 def move_detections(
     detections: Detections,
     offset: np.ndarray,
-    resolution_wh: Optional[Tuple[int, int]] = None,
+    resolution_wh: tuple[int, int] | None = None,
 ) -> Detections:
     """
     Args:
@@ -72,6 +75,8 @@ class InferenceSlicer:
             filtering or merging overlapping detections in slices.
         iou_threshold (float): Intersection over Union (IoU) threshold
             used when filtering by overlap.
+        match_metric (str): Metric used for matching detections in slices.
+            "IOU" or "IOS". Defaults "IOU".
         callback (Callable): A function that performs inference on a given image
             slice and returns detections.
         thread_workers (int): Number of threads for parallel execution.
@@ -86,11 +91,12 @@ class InferenceSlicer:
     def __init__(
         self,
         callback: Callable[[np.ndarray], Detections],
-        slice_wh: Tuple[int, int] = (320, 320),
-        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,
+        slice_wh: tuple[int, int] = (320, 320),
+        overlap_ratio_wh: tuple[float, float] | None = (0.2, 0.2),
+        overlap_wh: tuple[int, int] | None = None,
+        overlap_filter: OverlapFilter | str = OverlapFilter.NON_MAX_SUPPRESSION,
         iou_threshold: float = 0.5,
+        match_metric: str = "IOU",
         thread_workers: int = 1,
     ):
         if overlap_ratio_wh is not None:
@@ -106,6 +112,7 @@ class InferenceSlicer:
 
         self.slice_wh = slice_wh
         self.iou_threshold = iou_threshold
+        self.match_metric = match_metric
         self.overlap_filter = OverlapFilter.from_value(overlap_filter)
         self.callback = callback
         self.thread_workers = thread_workers
@@ -165,9 +172,13 @@ class InferenceSlicer:
         if self.overlap_filter == OverlapFilter.NONE:
             return merged
         elif self.overlap_filter == OverlapFilter.NON_MAX_SUPPRESSION:
-            return merged.with_nms(threshold=self.iou_threshold)
+            return merged.with_nms(
+                threshold=self.iou_threshold, match_metric=self.match_metric
+            )
         elif self.overlap_filter == OverlapFilter.NON_MAX_MERGE:
-            return merged.with_nmm(threshold=self.iou_threshold)
+            return merged.with_nmm(
+                threshold=self.iou_threshold, match_metric=self.match_metric
+            )
         else:
             warnings.warn(
                 f"Invalid overlap filter strategy: {self.overlap_filter}",
@@ -198,10 +209,10 @@ class InferenceSlicer:
 
     @staticmethod
     def _generate_offset(
-        resolution_wh: Tuple[int, int],
-        slice_wh: Tuple[int, int],
-        overlap_ratio_wh: Optional[Tuple[float, float]],
-        overlap_wh: Optional[Tuple[int, int]],
+        resolution_wh: tuple[int, int],
+        slice_wh: tuple[int, int],
+        overlap_ratio_wh: tuple[float, float] | None,
+        overlap_wh: tuple[int, int] | None,
     ) -> np.ndarray:
         """
         Generate offset coordinates for slicing an image based on the given resolution,
@@ -260,8 +271,8 @@ class InferenceSlicer:
 
     @staticmethod
     def _validate_overlap(
-        overlap_ratio_wh: Optional[Tuple[float, float]],
-        overlap_wh: Optional[Tuple[int, int]],
+        overlap_ratio_wh: tuple[float, float] | None,
+        overlap_wh: tuple[int, int] | None,
     ) -> None:
         if overlap_ratio_wh is not None and overlap_wh is not None:
             raise ValueError(

supervision/detection/tools/json_sink.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import json
 import os
-from typing import Any, Dict, List, Optional
+from typing import Any
 
 from supervision.detection.core import Detections
 
@@ -51,8 +51,8 @@ class JSONSink:
             None
         """
         self.file_name = file_name
-        self.file: Optional[open] = None
-        self.data: List[Dict[str, Any]] = []
+        self.file: open | None = None
+        self.data: list[dict[str, Any]] = []
 
     def __enter__(self) -> JSONSink:
         self.open()
@@ -60,9 +60,9 @@ class JSONSink:
 
     def __exit__(
         self,
-        exc_type: Optional[type],
-        exc_val: Optional[Exception],
-        exc_tb: Optional[Any],
+        exc_type: type | None,
+        exc_val: Exception | None,
+        exc_tb: Any | None,
     ) -> None:
         self.write_and_close()
 
@@ -92,8 +92,8 @@ class JSONSink:
 
     @staticmethod
     def parse_detection_data(
-        detections: Detections, custom_data: Optional[Dict[str, Any]] = None
-    ) -> List[Dict[str, Any]]:
+        detections: Detections, custom_data: dict[str, Any] | None = None
+    ) -> list[dict[str, Any]]:
         parsed_rows = []
         for i in range(len(detections.xyxy)):
             row = {
@@ -126,7 +126,7 @@ class JSONSink:
         return parsed_rows
 
     def append(
-        self, detections: Detections, custom_data: Optional[Dict[str, Any]] = None
+        self, detections: Detections, custom_data: dict[str, Any] | None = None
     ) -> None:
         """
         Append detection data to the JSON file.

supervision/detection/tools/polygon_zone.py

@@ -1,12 +1,15 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
 from dataclasses import replace
-from typing import Iterable, Optional
 
 import cv2
 import numpy as np
 import numpy.typing as npt
 
 from supervision import Detections
-from supervision.detection.utils import clip_boxes, polygon_to_mask
+from supervision.detection.utils.boxes import clip_boxes
+from supervision.detection.utils.converters import polygon_to_mask
 from supervision.draw.color import Color
 from supervision.draw.utils import draw_filled_polygon, draw_polygon, draw_text
 from supervision.geometry.core import Position
@@ -153,7 +156,7 @@ class PolygonZoneAnnotator:
         self.display_in_zone_count = display_in_zone_count
         self.opacity = opacity
 
-    def annotate(self, scene: np.ndarray, label: Optional[str] = None) -> np.ndarray:
+    def annotate(self, scene: np.ndarray, label: str | None = None) -> np.ndarray:
         """
         Annotates the polygon zone within a frame with a count of detected objects.
 

supervision/detection/tools/smoother.py

@@ -1,7 +1,8 @@
+from __future__ import annotations
+
 import warnings
 from collections import defaultdict, deque
 from copy import deepcopy
-from typing import Optional
 
 import numpy as np
 
@@ -95,7 +96,7 @@ class DetectionsSmoother:
 
         return self.get_smoothed_detections()
 
-    def get_track(self, track_id: int) -> Optional[Detections]:
+    def get_track(self, track_id: int) -> Detections | None:
         track = self.tracks.get(track_id, None)
         if track is None:
             return None

supervision/detection/tools/transformers.py

@@ -1,15 +1,17 @@
+from __future__ import annotations
+
 import io
-from typing import Any, Dict, Optional
+from typing import Any
 
 import numpy as np
 from PIL import Image
 
 from supervision.config import CLASS_NAME_DATA_FIELD
-from supervision.detection.utils import mask_to_xyxy
+from supervision.detection.utils.converters import mask_to_xyxy
 
 
 def process_transformers_detection_result(
-    detection_result: dict, id2label: Optional[Dict[int, str]]
+    detection_result: dict, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of Transformers object detection functions such as
@@ -38,7 +40,7 @@ def process_transformers_detection_result(
 
 
 def process_transformers_v4_segmentation_result(
-    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+    segmentation_result: dict, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of Transformers segmentation functions such as
@@ -77,7 +79,7 @@ def process_transformers_v4_segmentation_result(
 
 
 def process_transformers_v5_segmentation_result(
-    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+    segmentation_result: dict, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of Transformers segmentation functions such as
@@ -107,7 +109,7 @@ def process_transformers_v5_segmentation_result(
 
 
 def process_transformers_v5_semantic_or_instance_segmentation_result(
-    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+    segmentation_result: dict, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of Transformers segmentation functions such as
@@ -143,7 +145,7 @@ def process_transformers_v5_semantic_or_instance_segmentation_result(
 
 
 def process_transformers_v4_panoptic_segmentation_result(
-    segmentation_result: dict, id2label: Optional[Dict[int, str]]
+    segmentation_result: dict, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of the Transformers function `post_process_panoptic` (v4).
@@ -177,7 +179,7 @@ def process_transformers_v4_panoptic_segmentation_result(
 
 
 def process_transformers_v5_panoptic_segmentation_result(
-    segmentation_array: np.ndarray, id2label: Optional[Dict[int, str]]
+    segmentation_array: np.ndarray, id2label: dict[int, str] | None
 ) -> dict:
     """
     Process the result of the Transformers function
@@ -220,9 +222,9 @@ def png_string_to_segmentation_array(png_string: bytes) -> np.ndarray:
 
 def append_class_names_to_data(
     class_ids: np.ndarray,
-    id2label: Optional[Dict[int, str]],
-    data: Optional[Dict[str, Any]] = None,
-) -> Dict[str, Any]:
+    id2label: dict[int, str] | None,
+    data: dict[str, Any] | None = None,
+) -> dict[str, Any]:
     """
     Helper function to create or append to a data dictionary with class names if
     available.

supervision/detection/utils/boxes.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import numpy as np
+import numpy.typing as npt
+
+from supervision.detection.utils.iou_and_nms import box_iou_batch
+
+
+def clip_boxes(xyxy: np.ndarray, resolution_wh: tuple[int, int]) -> np.ndarray:
+    """
+    Clips bounding boxes coordinates to fit within the frame resolution.
+
+    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)`.
+        resolution_wh (Tuple[int, int]): A tuple of the form `(width, height)`
+            representing the resolution of the frame.
+
+    Returns:
+        np.ndarray: A numpy array of shape `(N, 4)` where each row
+            corresponds to a bounding box with coordinates clipped to fit
+            within the frame resolution.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [10, 20, 300, 200],
+            [15, 25, 350, 450],
+            [-10, -20, 30, 40]
+        ])
+
+        sv.clip_boxes(xyxy=xyxy, resolution_wh=(320, 240))
+        # array([
+        #     [ 10,  20, 300, 200],
+        #     [ 15,  25, 320, 240],
+        #     [  0,   0,  30,  40]
+        # ])
+        ```
+    """
+    result = np.copy(xyxy)
+    width, height = resolution_wh
+    result[:, [0, 2]] = result[:, [0, 2]].clip(0, width)
+    result[:, [1, 3]] = result[:, [1, 3]].clip(0, height)
+    return result
+
+
+def pad_boxes(xyxy: np.ndarray, px: int, py: int | None = None) -> np.ndarray:
+    """
+    Pads bounding boxes coordinates with a constant padding.
+
+    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)`.
+        px (int): The padding value to be added to both the left and right sides of
+            each bounding box.
+        py (Optional[int]): The padding value to be added to both the top and bottom
+            sides of each bounding box. If not provided, `px` will be used for both
+            dimensions.
+
+    Returns:
+        np.ndarray: A numpy array of shape `(N, 4)` where each row corresponds to a
+            bounding box with coordinates padded according to the provided padding
+            values.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [10, 20, 30, 40],
+            [15, 25, 35, 45]
+        ])
+
+        sv.pad_boxes(xyxy=xyxy, px=5, py=10)
+        # array([
+        #     [ 5, 10, 35, 50],
+        #     [10, 15, 40, 55]
+        # ])
+        ```
+    """
+    if py is None:
+        py = px
+
+    result = xyxy.copy()
+    result[:, [0, 1]] -= [px, py]
+    result[:, [2, 3]] += [px, py]
+
+    return result
+
+
+def denormalize_boxes(
+    normalized_xyxy: np.ndarray,
+    resolution_wh: tuple[int, int],
+    normalization_factor: float = 1.0,
+) -> np.ndarray:
+    """
+    Converts normalized bounding box coordinates to absolute pixel values.
+
+    Args:
+        normalized_xyxy (np.ndarray): A numpy array of shape `(N, 4)` where each row
+            contains normalized coordinates in the format `(x_min, y_min, x_max, y_max)`,
+            with values between 0 and `normalization_factor`.
+        resolution_wh (Tuple[int, int]): A tuple `(width, height)` representing the
+            target image resolution.
+        normalization_factor (float, optional): The normalization range of the input
+            coordinates. Defaults to 1.0.
+
+    Returns:
+        np.ndarray: An array of shape `(N, 4)` with absolute coordinates in
+            `(x_min, y_min, x_max, y_max)` format.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        # Default normalization (0-1)
+        normalized_xyxy = np.array([
+            [0.1, 0.2, 0.5, 0.6],
+            [0.3, 0.4, 0.7, 0.8]
+        ])
+        resolution_wh = (100, 200)
+        sv.denormalize_boxes(normalized_xyxy, resolution_wh)
+        # array([
+        #     [ 10.,  40.,  50., 120.],
+        #     [ 30.,  80.,  70., 160.]
+        # ])
+
+        # Custom normalization (0-100)
+        normalized_xyxy = np.array([
+            [10., 20., 50., 60.],
+            [30., 40., 70., 80.]
+        ])
+        sv.denormalize_boxes(normalized_xyxy, resolution_wh, normalization_factor=100.0)
+        # array([
+        #     [ 10.,  40.,  50., 120.],
+        #     [ 30.,  80.,  70., 160.]
+        # ])
+        ```
+    """  # noqa E501 // docs
+    width, height = resolution_wh
+    result = normalized_xyxy.copy()
+
+    result[[0, 2]] = (result[[0, 2]] * width) / normalization_factor
+    result[[1, 3]] = (result[[1, 3]] * height) / normalization_factor
+
+    return result
+
+
+def move_boxes(
+    xyxy: npt.NDArray[np.float64], offset: npt.NDArray[np.int32]
+) -> npt.NDArray[np.float64]:
+    """
+    Parameters:
+        xyxy (npt.NDArray[np.float64]): An array of shape `(n, 4)` containing the
+            bounding boxes coordinates in format `[x1, y1, x2, y2]`
+        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
+
+        xyxy = np.array([
+            [10, 10, 20, 20],
+            [30, 30, 40, 40]
+        ])
+        offset = np.array([5, 5])
+
+        sv.move_boxes(xyxy=xyxy, offset=offset)
+        # array([
+        #    [15, 15, 25, 25],
+        #    [35, 35, 45, 45]
+        # ])
+        ```
+    """
+    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 scale_boxes(
+    xyxy: npt.NDArray[np.float64], factor: float
+) -> npt.NDArray[np.float64]:
+    """
+    Scale the dimensions of bounding boxes.
+
+    Parameters:
+        xyxy (npt.NDArray[np.float64]): An array of shape `(n, 4)` containing the
+            bounding boxes coordinates in format `[x1, y1, x2, y2]`
+        factor (float): A float value representing the factor by which the box
+            dimensions are scaled. A factor greater than 1 enlarges the boxes, while a
+            factor less than 1 shrinks them.
+
+    Returns:
+        npt.NDArray[np.float64]: Scaled bounding boxes.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [10, 10, 20, 20],
+            [30, 30, 40, 40]
+        ])
+
+        sv.scale_boxes(xyxy=xyxy, factor=1.5)
+        # array([
+        #    [ 7.5,  7.5, 22.5, 22.5],
+        #    [27.5, 27.5, 42.5, 42.5]
+        # ])
+        ```
+    """
+    centers = (xyxy[:, :2] + xyxy[:, 2:]) / 2
+    new_sizes = (xyxy[:, 2:] - xyxy[:, :2]) * factor
+    return np.concatenate((centers - new_sizes / 2, centers + new_sizes / 2), axis=1)
+
+
+def spread_out_boxes(
+    xyxy: np.ndarray,
+    max_iterations: int = 100,
+) -> np.ndarray:
+    """
+    Spread out boxes that overlap with each other.
+
+    Args:
+        xyxy: Numpy array of shape (N, 4) where N is the number of boxes.
+        max_iterations: Maximum number of iterations to run the algorithm for.
+    """
+    if len(xyxy) == 0:
+        return xyxy
+
+    xyxy_padded = pad_boxes(xyxy, px=1)
+    for _ in range(max_iterations):
+        # NxN
+        iou = box_iou_batch(xyxy_padded, xyxy_padded)
+        np.fill_diagonal(iou, 0)
+        if np.all(iou == 0):
+            break
+
+        overlap_mask = iou > 0
+
+        # Nx2
+        centers = (xyxy_padded[:, :2] + xyxy_padded[:, 2:]) / 2
+
+        # NxNx2
+        delta_centers = centers[:, np.newaxis, :] - centers[np.newaxis, :, :]
+        delta_centers *= overlap_mask[:, :, np.newaxis]
+
+        # Nx2
+        delta_sum = np.sum(delta_centers, axis=1)
+        delta_magnitude = np.linalg.norm(delta_sum, axis=1, keepdims=True)
+        direction_vectors = np.divide(
+            delta_sum,
+            delta_magnitude,
+            out=np.zeros_like(delta_sum),
+            where=delta_magnitude != 0,
+        )
+
+        force_vectors = np.sum(iou, axis=1)
+        force_vectors = force_vectors[:, np.newaxis] * direction_vectors
+
+        force_vectors *= 10
+        force_vectors[(force_vectors > 0) & (force_vectors < 2)] = 2
+        force_vectors[(force_vectors < 0) & (force_vectors > -2)] = -2
+
+        force_vectors = force_vectors.astype(int)
+
+        xyxy_padded[:, [0, 1]] += force_vectors
+        xyxy_padded[:, [2, 3]] += force_vectors
+
+    return pad_boxes(xyxy_padded, px=-1)

supervision/detection/utils/converters.py

@@ -0,0 +1,272 @@
+import cv2
+import numpy as np
+
+MIN_POLYGON_POINT_COUNT = 3
+
+
+def xyxy_to_polygons(box: np.ndarray) -> np.ndarray:
+    """
+    Convert an array of boxes to an array of polygons.
+    Retains the input datatype.
+
+    Args:
+        box (np.ndarray): An array of boxes (N, 4), where each box is represented as a
+            list of four coordinates in the format `(x_min, y_min, x_max, y_max)`.
+
+    Returns:
+        np.ndarray: An array of polygons (N, 4, 2), where each polygon is
+            represented as a list of four coordinates in the format `(x, y)`.
+    """
+    polygon = np.zeros((box.shape[0], 4, 2), dtype=box.dtype)
+    polygon[:, :, 0] = box[:, [0, 2, 2, 0]]
+    polygon[:, :, 1] = box[:, [1, 1, 3, 3]]
+    return polygon
+
+
+def polygon_to_mask(polygon: np.ndarray, resolution_wh: tuple[int, int]) -> np.ndarray:
+    """Generate a mask from a polygon.
+
+    Args:
+        polygon (np.ndarray): The polygon for which the mask should be generated,
+            given as a list of vertices.
+        resolution_wh (Tuple[int, int]): The width and height of the desired resolution.
+
+    Returns:
+        np.ndarray: The generated 2D mask, where the polygon is marked with
+            `1`'s and the rest is filled with `0`'s.
+    """
+    width, height = map(int, resolution_wh)
+    mask = np.zeros((height, width), dtype=np.uint8)
+    cv2.fillPoly(mask, [polygon.astype(np.int32)], color=1)
+    return mask
+
+
+def xywh_to_xyxy(xywh: np.ndarray) -> np.ndarray:
+    """
+    Converts bounding box coordinates from `(x, y, width, height)`
+    format to `(x_min, y_min, x_max, y_max)` format.
+
+    Args:
+        xywh (np.ndarray): A numpy array of shape `(N, 4)` where each row
+            corresponds to a bounding box in the format `(x, y, width, height)`.
+
+    Returns:
+        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)`.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xywh = np.array([
+            [10, 20, 30, 40],
+            [15, 25, 35, 45]
+        ])
+
+        sv.xywh_to_xyxy(xywh=xywh)
+        # array([
+        #     [10, 20, 40, 60],
+        #     [15, 25, 50, 70]
+        # ])
+        ```
+    """
+    xyxy = xywh.copy()
+    xyxy[:, 2] = xywh[:, 0] + xywh[:, 2]
+    xyxy[:, 3] = xywh[:, 1] + xywh[:, 3]
+    return xyxy
+
+
+def xyxy_to_xywh(xyxy: np.ndarray) -> np.ndarray:
+    """
+    Converts bounding box coordinates from `(x_min, y_min, x_max, y_max)`
+    format to `(x, y, width, height)` format.
+
+    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)`.
+
+    Returns:
+        np.ndarray: A numpy array of shape `(N, 4)` where each row corresponds
+            to a bounding box in the format `(x, y, width, height)`.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [10, 20, 40, 60],
+            [15, 25, 50, 70]
+        ])
+
+        sv.xyxy_to_xywh(xyxy=xyxy)
+        # array([
+        #     [10, 20, 30, 40],
+        #     [15, 25, 35, 45]
+        # ])
+        ```
+    """
+    xywh = xyxy.copy()
+    xywh[:, 2] = xyxy[:, 2] - xyxy[:, 0]
+    xywh[:, 3] = xyxy[:, 3] - xyxy[:, 1]
+    return xywh
+
+
+def xcycwh_to_xyxy(xcycwh: np.ndarray) -> np.ndarray:
+    """
+    Converts bounding box coordinates from `(center_x, center_y, width, height)`
+    format to `(x_min, y_min, x_max, y_max)` format.
+
+    Args:
+        xcycwh (np.ndarray): A numpy array of shape `(N, 4)` where each row
+            corresponds to a bounding box in the format `(center_x, center_y, width,
+            height)`.
+
+    Returns:
+        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)`.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xcycwh = np.array([
+            [50, 50, 20, 30],
+            [30, 40, 10, 15]
+        ])
+
+        sv.xcycwh_to_xyxy(xcycwh=xcycwh)
+        # array([
+        #     [40, 35, 60, 65],
+        #     [25, 32.5, 35, 47.5]
+        # ])
+        ```
+    """
+    xyxy = xcycwh.copy()
+    xyxy[:, 0] = xcycwh[:, 0] - xcycwh[:, 2] / 2
+    xyxy[:, 1] = xcycwh[:, 1] - xcycwh[:, 3] / 2
+    xyxy[:, 2] = xcycwh[:, 0] + xcycwh[:, 2] / 2
+    xyxy[:, 3] = xcycwh[:, 1] + xcycwh[:, 3] / 2
+    return xyxy
+
+
+def xyxy_to_xcycarh(xyxy: np.ndarray) -> np.ndarray:
+    """
+    Converts bounding box coordinates from `(x_min, y_min, x_max, y_max)`
+    into measurement space to format `(center x, center y, aspect ratio, height)`,
+    where the aspect ratio is `width / height`.
+
+    Args:
+        xyxy (np.ndarray): Bounding box in format `(x1, y1, x2, y2)`.
+            Expected shape is `(N, 4)`.
+    Returns:
+        np.ndarray: Bounding box in format
+            `(center x, center y, aspect ratio, height)`. Shape `(N, 4)`.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [10, 20, 40, 60],
+            [15, 25, 50, 70]
+        ])
+
+        sv.xyxy_to_xcycarh(xyxy=xyxy)
+        # array([
+        #     [25.  , 40.  ,  0.75, 40.  ],
+        #     [32.5 , 47.5 ,  0.77777778, 45.  ]
+        # ])
+        ```
+
+    """
+    if xyxy.size == 0:
+        return np.empty((0, 4), dtype=float)
+
+    x1, y1, x2, y2 = xyxy.T
+    width = x2 - x1
+    height = y2 - y1
+    center_x = x1 + width / 2
+    center_y = y1 + height / 2
+
+    aspect_ratio = np.divide(
+        width,
+        height,
+        out=np.zeros_like(width, dtype=float),
+        where=height != 0,
+    )
+    result = np.column_stack((center_x, center_y, aspect_ratio, height))
+    return result.astype(float)
+
+
+def mask_to_xyxy(masks: np.ndarray) -> np.ndarray:
+    """
+    Converts a 3D `np.array` of 2D bool masks into a 2D `np.array` of bounding boxes.
+
+    Parameters:
+        masks (np.ndarray): A 3D `np.array` of shape `(N, W, H)`
+            containing 2D bool masks
+
+    Returns:
+        np.ndarray: A 2D `np.array` of shape `(N, 4)` containing the bounding boxes
+            `(x_min, y_min, x_max, y_max)` for each mask
+    """
+    n = masks.shape[0]
+    xyxy = np.zeros((n, 4), dtype=int)
+
+    for i, mask in enumerate(masks):
+        rows, cols = np.where(mask)
+
+        if len(rows) > 0 and len(cols) > 0:
+            x_min, x_max = np.min(cols), np.max(cols)
+            y_min, y_max = np.min(rows), np.max(rows)
+            xyxy[i, :] = [x_min, y_min, x_max, y_max]
+
+    return xyxy
+
+
+def mask_to_polygons(mask: np.ndarray) -> list[np.ndarray]:
+    """
+    Converts a binary mask to a list of polygons.
+
+    Parameters:
+        mask (np.ndarray): A binary mask represented as a 2D NumPy array of
+            shape `(H, W)`, where H and W are the height and width of
+            the mask, respectively.
+
+    Returns:
+        List[np.ndarray]: A list of polygons, where each polygon is represented by a
+            NumPy array of shape `(N, 2)`, containing the `x`, `y` coordinates
+            of the points. Polygons with fewer points than `MIN_POLYGON_POINT_COUNT = 3`
+            are excluded from the output.
+    """
+
+    contours, _ = cv2.findContours(
+        mask.astype(np.uint8), cv2.RETR_TREE, cv2.CHAIN_APPROX_SIMPLE
+    )
+    return [
+        np.squeeze(contour, axis=1)
+        for contour in contours
+        if contour.shape[0] >= MIN_POLYGON_POINT_COUNT
+    ]
+
+
+def polygon_to_xyxy(polygon: np.ndarray) -> np.ndarray:
+    """
+    Converts a polygon represented by a NumPy array into a bounding box.
+
+    Parameters:
+        polygon (np.ndarray): A polygon represented by a NumPy array of shape `(N, 2)`,
+            containing the `x`, `y` coordinates of the points.
+
+    Returns:
+        np.ndarray: A 1D NumPy array containing the bounding box
+            `(x_min, y_min, x_max, y_max)` of the input polygon.
+    """
+    x_min, y_min = np.min(polygon, axis=0)
+    x_max, y_max = np.max(polygon, axis=0)
+    return np.array([x_min, y_min, x_max, y_max])