Merge pull request #1741 from roboflow/main

merge `supervision-0.25.1` hot fix into `main` before `supervision-0.26.0` release
Merge branch 'develop' into main
2024-12-16 16:26:56 +01:00 · 2024-12-16 16:22:01 +01:00 · 2024-12-16 14:35:22 +01:00 · 2024-12-16 13:27:42 +00:00 · 2024-12-16 14:27:13 +01:00 · 2024-12-14 23:47:26 +03:00
48 changed files with 2644 additions and 1149 deletions
@@ -0,0 +1,4 @@
+# These owners will be the default owners for everything in
+# the repo. They will be requested for review when someone
+# opens a pull request.
+*   @SkalskiP @onuralpszr
@@ -4,13 +4,15 @@ updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
-      interval: "daily"
+      interval: "weekly"
    commit-message:
      prefix: ⬆️
+    target-branch: "develop"
  # Python
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
-      interval: "daily"
+      interval: "weekly"
    commit-message:
      prefix: ⬆️
+    target-branch: "develop"
@@ -1,33 +1,42 @@
-
 name: Clear cache

 on:
-    schedule:
-      - cron: '0 0 1 * *'
-    workflow_dispatch:
+  schedule:
+    - cron: "0 0 1 * *" # Run at midnight on the first day of every month
+  workflow_dispatch:

+# Restrict permissions by default
 permissions:
-  actions: write
+  actions: write # Required for cache management

 jobs:
  clear-cache:
+    name: Clear cache
    runs-on: ubuntu-latest
+    timeout-minutes: 10
    steps:
      - name: Clear cache
-        uses: actions/github-script@v7
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
        with:
          script: |
-            console.log("About to clear")
+            console.log("Starting cache cleanup...")
            const caches = await github.rest.actions.getActionsCacheList({
              owner: context.repo.owner,
              repo: context.repo.repo,
            })
+
+            let deletedCount = 0
            for (const cache of caches.data.actions_caches) {
-              console.log(cache)
-              github.rest.actions.deleteActionsCacheById({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                cache_id: cache.id,
-              })
+              console.log(`Deleting cache: ${cache.key} (${cache.size_in_bytes} bytes)`)
+              try {
+                await github.rest.actions.deleteActionsCacheById({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  cache_id: cache.id,
+                })
+                deletedCount++
+              } catch (error) {
+                console.error(`Failed to delete cache ${cache.key}: ${error.message}`)
+              }
            }
-            console.log("Clear completed")
+            console.log(`Cache cleanup completed. Deleted ${deletedCount} caches.`)
@@ -0,0 +1,22 @@
+name: Combine Dependabot PRs
+
+on:
+  schedule:
+    - cron: "0 1 * * 3" # Wednesday at 01:00
+  workflow_dispatch: # allows you to manually trigger the workflow
+
+permissions:
+  contents: write
+  pull-requests: write
+  checks: read
+
+jobs:
+  combine-prs:
+    name: Combine
+    runs-on: ubuntu-latest
+    steps:
+      - name: combine-prs
+        id: combine-prs
+        uses: github/combine-prs@2909f404763c3177a456e052bdb7f2e85d3a7cb3 # v5.2.0
+        with:
+          labels: combined-pr
@@ -1,64 +0,0 @@
-name: Notebook Check Pull Request
-
-on:
-  pull_request_target:
-    types: [opened, reopened]
-
-permissions:
-  contents: read
-
-jobs:
-  comment-welcome:
-    permissions:
-      contents: read
-      pull-requests: write
-
-    runs-on: ubuntu-latest
-    steps:
-    - name: Fetch pull request branch
-      uses: actions/checkout@v4
-      with:
-        repository: ${{ github.event.pull_request.head.repo.full_name }}
-        ref: ${{ github.event.pull_request.head.sha }}
-    - name: Fetch base develop branch
-      run: git fetch -u "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY" develop:develop
-    - name: Create message
-      env:
-        HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}
-        HEAD_REF: ${{ github.event.pull_request.head.ref }}
-        PR_NUM: ${{ github.event.pull_request.number }}
-      run: |
-        # Preview links and tool usage only needed for notebook changes.
-        readarray -t changed_notebooks < <(git diff --name-only develop | grep '\.ipynb$' || true)
-        if [[ ${#changed_notebooks[@]} == 0 ]]; then
-          echo "No notebooks modified in this pull request."
-        else
-          msg="<h4>Preview</h4>\n"
-          msg+="Preview and run these notebook edits with Google Colab:\n<ul>\n"
-          # Link to PR branch in user's fork that is always current.
-          for fp in "${changed_notebooks[@]}"; do
-            gh_path="${HEAD_REPOSITORY}/blob/${HEAD_REF}/${fp}"
-            colab_url="https://colab.research.google.com/github/${gh_path}"
-            msg+="<li><a href='${colab_url}'>${fp}</a></li>\n"
-          done
-          msg+="</ul>\n"
-
-          reviewnb_url="https://app.reviewnb.com/${GITHUB_REPOSITORY}/pull/${PR_NUM}/files/"
-          msg+="Rendered <a href='${reviewnb_url}'>notebook diffs</a> available on ReviewNB.com.\n"
-
-          msg+="If commits are added to the pull request, synchronize your local branch: <code>git pull origin $HEAD_REF</code>\n"
-        fi
-        echo "MESSAGE=$msg" >> $GITHUB_ENV
-    - name: Post comment
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        ISSUE_URL: ${{ github.event.pull_request.issue_url }}
-      run: |
-        # Env var defined in previous step. Escape string for JSON.
-        body="$(echo -n -e $MESSAGE | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
-        # Add comment to pull request.
-        curl -X POST \
-          -H "Accept: application/vnd.github.v3+json" \
-          -H "Authorization: token $GITHUB_TOKEN" \
-          "${ISSUE_URL}/comments" \
-          --data "{\"body\": $body}"
@@ -2,16 +2,18 @@ name: 🔧 Poetry Check and Installation Test Workflow
 on:
  push:
    paths:
-      - 'poetry.lock'
-      - 'pyproject.toml'
+      - "poetry.lock"
+      - "pyproject.toml"
  pull_request:
    paths:
-      - 'poetry.lock'
-      - 'pyproject.toml'
+      - "poetry.lock"
+      - "pyproject.toml"
  workflow_dispatch:

 jobs:
  poetry-tests:
+    name: Poetry install and check
+    timeout-minutes: 10
    strategy:
      fail-fast: false
      matrix:
@@ -20,18 +22,21 @@ jobs:
    runs-on: ${{ matrix.os }}
    steps:
      - name: 📥 Checkout the repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
        with:
          python-version: ${{ matrix.python-version }}

-      - name: 📦 Install the base dependencies
-        run: python -m pip install --upgrade poetry
+      - name: 📜 Setup Poetry
+        uses: abatilo/actions-poetry@e78f54a89cb052fff327414dd9ff010b5d2b4dbd # v3.0.1

      - name: 🔍 Check the correctness of the project config
        run: poetry check

      - name: 🚀 Do Install the package Test
-        run: poetry install
+        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__)"
@@ -1,53 +0,0 @@
-name: Docs WorkFlow - Develop Tag 📚
-
-on:
-  push:
-    branches:
-      - develop
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.ref}}
-  cancel-in-progress: true
-
-permissions:
-  contents: write
-  pages: write
-  pull-requests: write
-
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - name: 🔄 Checkout code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: 🐍 Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.10'
-      - name: 📦 Install mkdocs-material
-        run: pip install "mkdocs-material"
-      - name: 📦 Install mkdocstrings[python]
-        run: pip install "mkdocstrings[python]"
-      - name: 📦 Install mkdocs-material[imaging]
-        run: pip install "mkdocs-material[imaging]"
-      - name: 📦 Install mike
-        run: pip install "mike"
-      - name: 📦 Install mkdocs-git-revision-date-localized-plugin
-        run: pip install "mkdocs-git-revision-date-localized-plugin"
-      - name: 📦 Install JupyterLab
-        run: pip install jupyterlab
-      - name: 📦 Install mkdocs-jupyter
-        run: pip install mkdocs-jupyter
-      - name: 📦 Install mkdocs-git-committers-plugin-2
-        run: pip install mkdocs-git-committers-plugin-2
-      - name: ⚙️ Configure git for github-actions
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
-      - name: 🚀 Deploy MkDoc-Material with mike
-        run: |
-          MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} mike deploy --push develop
@@ -0,0 +1,62 @@
+name: Build and Publish Docs
+
+on:
+  push:
+    branches:
+      - develop
+  workflow_dispatch:
+  release:
+    types: [published]
+
+# Ensure only one concurrent deployment
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.ref}}
+  cancel-in-progress: true
+
+# Restrict permissions by default
+permissions:
+  contents: write # Required for committing to gh-pages
+  pages: write # Required for deploying to Pages
+  pull-requests: write # Required for PR comments
+
+jobs:
+  deploy:
+    name: Publish Docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - 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@e78f54a89cb052fff327414dd9ff010b5d2b4dbd # v3.0.1
+
+      - name: 📦 Install dependencies
+        run: |
+          poetry install --with=docs
+
+      - name: ⚙️ Configure git for github-actions
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: 🚀 Deploy 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
+
+      - 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
@@ -1,55 +0,0 @@
-name: Supervision Release Documentation Workflow 📚
-on:
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.ref}}
-  cancel-in-progress: true
-
-permissions:
-  contents: write
-  pages: write
-  pull-requests: write
-
-
-jobs:
-  doc-build-deploy:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.10"]
-    steps:
-      - name: 🛎️ Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          ref: ${{ github.head_ref }}
-
-      - name: 🐍 Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.10'
-      - name: 📦 Install mkdocs-material
-        run: pip install "mkdocs-material"
-      - name: 📦 Install mkdocstrings[python]
-        run: pip install "mkdocstrings[python]"
-      - name: 📦 Install mkdocs-material[imaging]
-        run: pip install "mkdocs-material[imaging]"
-      - name: 📦 Install mike
-        run: pip install "mike"
-      - name: 📦 Install mkdocs-git-revision-date-localized-plugin
-        run: pip install "mkdocs-git-revision-date-localized-plugin"
-      - name: 📦 Install JupyterLab
-        run: pip install jupyterlab
-      - name: 📦 Install mkdocs-jupyter
-        run: pip install mkdocs-jupyter
-      - name: 📦 Install mkdocs-git-committers-plugin-2
-        run: pip install mkdocs-git-committers-plugin-2
-      - name: ⚙️ Configure git for github-actions 👷
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
-      - name: 🚀 Deploy MkDoc-Material 📚
-        run: |
-            latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`)
-            MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} mike deploy --push --update-aliases $latest_tag latest
@@ -1,43 +1,52 @@
 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-pypi:
-    name: Build and publish to PyPI
+  build-and-publish-pre-release:
+    name: Publish  Pre-releasePackage
    runs-on: ubuntu-latest
-    environment: test
+    environment: release
+    timeout-minutes: 10
    permissions:
-      id-token: write
+      id-token: write # Required for PyPI publishing
+      contents: read # Required for checkout
    strategy:
      matrix:
        python-version: ["3.10"]
    steps:
-      - name: 🛎️ Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.head_ref }}
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
      - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
        with:
          python-version: ${{ matrix.python-version }}

+      - name: 📜 Setup Poetry
+        uses: abatilo/actions-poetry@e78f54a89cb052fff327414dd9ff010b5d2b4dbd # v3.0.1
+
      - name: 🏗️ Build source and wheel distributions
        run: |
-          python -m pip install --upgrade build twine
-          python -m build
+          poetry install --with=build
+          poetry build
          twine check --strict dist/*

      - name: 🚀 Publish to PyPi
-        uses: pypa/gh-action-pypi-publish@release/v1.10
+        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
+        with:
+          attestations: true

      - name: 🚀 Publish to Test-PyPi
-        uses: pypa/gh-action-pypi-publish@release/v1.10
+        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
        with:
          repository-url: https://test.pypi.org/legacy/
+          attestations: true
@@ -1,40 +1,50 @@
 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
+      id-token: write # Required for PyPI publishing
+      contents: read # Required for checkout
    strategy:
      matrix:
        python-version: ["3.10"]
    steps:
-      - name: 🛎️ Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.head_ref }}
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
      - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
        with:
          python-version: ${{ matrix.python-version }}

+      - name: 📜 Setup Poetry
+        uses: abatilo/actions-poetry@e78f54a89cb052fff327414dd9ff010b5d2b4dbd # v3.0.1
+
      - name: 🏗️ Build source and wheel distributions
        run: |
-          python -m pip install --upgrade build twine
-          python -m build
+          poetry install --with=build
+          poetry build
          twine check --strict dist/*

      - name: 🚀 Publish to PyPi
-        uses: pypa/gh-action-pypi-publish@release/v1.10
+        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
+        with:
+          attestations: true

      - name: 🚀 Publish to Test-PyPi
-        uses: pypa/gh-action-pypi-publish@release/v1.10
+        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
        with:
          repository-url: https://test.pypi.org/legacy/
+          attestations: true
@@ -4,18 +4,37 @@ on:
  pull_request:
    branches: [main, develop]

+# Restrict permissions by default
+permissions:
+  contents: read # Required for checkout
+  checks: write # Required for test reporting
+
 jobs:
  docs-build-test:
+    name: Test docs build
    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        python-version: ["3.10"]
    steps:
-      - name: 🔄 Checkout code
-        uses: actions/checkout@v4
-      - name: 🐍 Set up Python
-        uses: actions/setup-python@v5
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
-          python-version: '3.10'
-      - name:  🏗️ Install dependencies and Test Docs Build
+          fetch-depth: 0
+
+      - 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@e78f54a89cb052fff327414dd9ff010b5d2b4dbd # v3.0.1
+
+      - name: 🏗️ Install dependencies
        run: |
-          python -m pip install --upgrade pip
-          pip install "mkdocs-material" "mkdocstrings[python]" "mkdocs-material[imaging]" mike "mkdocs-git-revision-date-localized-plugin" jupyterlab mkdocs-jupyter mkdocs-git-committers-plugin-2
-          mkdocs build --verbose
+          poetry install --with=docs
+
+      - name: 🧪 Test Docs Build
+        run: |
+          poetry run mkdocs build --verbose
@@ -1,58 +0,0 @@
-name: Python 3.8 - Min Dep Test WorkFlow
-
-on:
-  pull_request:
-    branches: [main, develop]
-
-jobs:
-  build-min-dep-test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.8"]
-    steps:
-      - name: 🛎️ Checkout
-        uses: actions/checkout@v4
-      - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        # id based on python version
-        id: python-setup
-        with:
-          python-version: ${{ matrix.python-version }}
-          check-latest: true
-
-      - name: 📦 Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install \
-              attrs==23.1.0 \
-              certifi==2023.7.22 \
-              charset-normalizer==2.0.12 \
-              cycler==0.12.1 \
-              exceptiongroup==1.1.3 \
-              fonttools==4.43.1 \
-              idna==3.4 \
-              iniconfig==2.0.0 \
-              kiwisolver==1.4.5 \
-              matplotlib==3.5.0 \
-              numpy==1.21.2 \
-              opencv-python==4.5.5.64 \
-              Pillow==10.1.0 \
-              packaging==23.2 \
-              pluggy==1.3.0 \
-              pyparsing==3.1.1 \
-              pytest==7.2.0 \
-              python-dateutil==2.8.2 \
-              PyYAML==5.3 \
-              requests==2.26.0 \
-              scipy==1.10.0 \
-              setuptools-scm==8.0.4 \
-              six==1.16.0 \
-              tomli==2.0.1 \
-              tqdm==4.62.3 \
-              typing_extensions==4.8.0 \
-              urllib3==1.26.18 \
-              defusedxml==0.7.1
-
-      - name: 🧪 Test
-        run: "python -m pytest ./test"
@@ -4,26 +4,44 @@ on:
  pull_request:
    branches: [main, develop]

+permissions:
+  contents: read
+  checks: write # Required for test reporting
+  pull-requests: write # Required for PR comments
+
 jobs:
-  build-dev-test:
-    runs-on: ubuntu-latest
+  pytest:
+    name: PyTest
+    timeout-minutes: 10
    strategy:
      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false # Continue with other versions if one fails
+    runs-on: ${{ matrix.os }}
    steps:
-      - name: 🛎️ Checkout
-        uses: actions/checkout@v4
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
      - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
        with:
          python-version: ${{ matrix.python-version }}
-          check-latest: true
+
+      - name: 📜 Setup Poetry
+        uses: abatilo/actions-poetry@e78f54a89cb052fff327414dd9ff010b5d2b4dbd # v3.0.1

      - name: 📦 Install dependencies
        run: |
-          python -m pip install --upgrade pip
-          pip install .
-          pip install pytest
+          poetry install --with=test

-      - name: 🧪 Test
-        run: "python -m pytest ./test"
+      - name: Run pytest
+        uses: pavelzw/pytest-action@510c5e90c360a185039bea56ce8b3e7e51a16507 # v2.2.0
+        with:
+          verbose: true
+          emoji: true
+          job-summary: true
+          custom-arguments: "-q"
+          click-to-expand: true
+          report-title: "Test Report"
+          custom-pytest: "poetry run pytest"
@@ -25,14 +25,14 @@ repos:
      - id: mixed-line-ending

  -   repo: https://github.com/PyCQA/bandit
-      rev: '1.7.10'
+      rev: '1.8.0'
      hooks:
      -   id: bandit
          args: ["-c", "pyproject.toml"]
          additional_dependencies: ["bandit[toml]"]

  -   repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.7.3
+      rev: v0.8.2
      hooks:
      -   id: ruff
          args: [--fix, --exit-non-zero-on-fix]
@@ -128,15 +128,26 @@ PRs must pass all tests and linting requirements before they can be merged.

 Before starting your work on the project, set up your development environment:

-1. Clone your fork of the project:
+1. Clone your fork of the project (recommended to use shallow clone of develop branch):
+
+    **Option A: Recommended for most contributors (shallow clone of develop branch):**
+
+    ```bash
+    git clone --depth 1 -b develop https://github.com/YOUR_USERNAME/supervision.git
+    cd supervision
+    ```
+
+    Replace `YOUR_USERNAME` with your GitHub username.
+
+    > Note: Using `--depth 1` creates a shallow clone with minimal history and `-b develop` ensures you start with the development branch. This significantly reduces download size while providing everything needed to contribute.
+
+    **Option B: Full repository clone (if you need complete history):**

    ```bash
    git clone https://github.com/YOUR_USERNAME/supervision.git
    cd supervision
    ```

-    Replace `YOUR_USERNAME` with your GitHub username.
-
 2. Create and activate a virtual environment:

    ```bash
@@ -353,7 +353,7 @@
   },
   "outputs": [],
   "source": [
-    "!pip install -q ultralytics"
+    "!pip install -q \"ultralytics<=8.3.40\""
   ]
  },
  {
@@ -1,6 +1,5 @@
 ---
 comments: true
-status: new
 ---

 # Assets
@@ -8,17 +7,6 @@ status: new
 Supervision offers an assets download utility that allows you to download video files
 that you can use in your demos.

-## Install extra
-
-To install the Supervision assets utility, you can use `pip`. This utility is available
-as an extra within the Supervision package.
-
-!!! example "pip install"
-
-    ```bash
-    pip install "supervision[assets]"
-    ```
-
 <div class="md-typeset">
    <h2><a href="#supervision.assets.downloader.download_assets.download_assets">download_assets</a></h2>
 </div>
@@ -28,26 +28,28 @@ 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"

@@ -234,7 +236,8 @@ Annotators accept detections and apply box or mask visualizations to the detecti

    <div class="result" markdown>

-    ![mask-annotator-example](https://media.roboflow.com/supervision-annotator-examples/mask-annotator-example-purple.png){ align=center width="800" }
+    ![mask-annotator-example](https://media.roboflow.com/supervision-annotator-examples/
+    mask-annotator-example-purple.png){ align=center width="800" }

    </div>

@@ -255,7 +258,8 @@ Annotators accept detections and apply box or mask visualizations to the detecti

    <div class="result" markdown>

-    ![polygon-annotator-example](https://media.roboflow.com/supervision-annotator-examples/polygon-annotator-example-purple.png){ align=center width="800" }
+    ![polygon-annotator-example](https://media.roboflow.com/supervision-annotator-examples/
+    polygon-annotator-example-purple.png){ align=center width="800" }

    </div>

@@ -283,7 +287,8 @@ Annotators accept detections and apply box or mask visualizations to the detecti

    <div class="result" markdown>

-    ![label-annotator-example](https://media.roboflow.com/supervision-annotator-examples/label-annotator-example-purple.png){ align=center width="800" }
+    ![label-annotator-example](https://media.roboflow.com/supervision-annotator-examples/
+    label-annotator-example-purple.png){ align=center width="800" }

    </div>

@@ -314,7 +319,8 @@ Annotators accept detections and apply box or mask visualizations to the detecti

    <div class="result" markdown>

-    ![label-annotator-example](https://media.roboflow.com/supervision-annotator-examples/label-annotator-example-purple.png){ align=center width="800" }
+    ![label-annotator-example](https://media.roboflow.com/supervision-annotator-examples/
+    label-annotator-example-purple.png){ align=center width="800" }

    </div>

@@ -341,24 +347,32 @@ Annotators accept detections and apply box or mask visualizations to the detecti

    <div class="result" markdown>

-    ![icon-annotator-example](https://media.roboflow.com/supervision-annotator-examples/icon-annotator-example.png){ align=center width="800" }
+    ![icon-annotator-example](https://media.roboflow.com/supervision-annotator-examples/
+    icon-annotator-example.png){ align=center width="800" }

    </div>

-=== "Crop"
+    <!-- === "Crop"

-    ```python
-    import supervision as sv
+        ```python
+        import supervision as sv

-    image = ...
-    detections = sv.Detections(...)
+        image = ...
+        detections = sv.Detections(...)

-    crop_annotator = sv.CropAnnotator()
-    annotated_frame = crop_annotator.annotate(
-        scene=image.copy(),
-        detections=detections
-    )
-    ```
+        crop_annotator = sv.CropAnnotator()
+        annotated_frame = crop_annotator.annotate(
+            scene=image.copy(),
+            detections=detections
+        )
+        ```
+        <div class="result" markdown>
+
+        ![crop-annotator-example](https://media.roboflow.com/supervision-annotator-examples/
+        crop-annotator-example.png){ align=center width="800" }
+
+        </div>
+    -->

 === "Blur"

@@ -377,7 +391,8 @@ Annotators accept detections and apply box or mask visualizations to the detecti

    <div class="result" markdown>

-    ![blur-annotator-example](https://media.roboflow.com/supervision-annotator-examples/blur-annotator-example-purple.png){ align=center width="800" }
+    ![blur-annotator-example](https://media.roboflow.com/supervision-annotator-examples/
+    blur-annotator-example-purple.png){ align=center width="800" }

    </div>

@@ -398,7 +413,8 @@ Annotators accept detections and apply box or mask visualizations to the detecti

    <div class="result" markdown>

-    ![pixelate-annotator-example](https://media.roboflow.com/supervision-annotator-examples/pixelate-annotator-example-10.png){ align=center width="800" }
+    ![pixelate-annotator-example](https://media.roboflow.com/supervision-annotator-examples/
+    pixelate-annotator-example-10.png){ align=center width="800" }

    </div>

@@ -429,7 +445,8 @@ Annotators accept detections and apply box or mask visualizations to the detecti

    <div class="result" markdown>

-    ![trace-annotator-example](https://media.roboflow.com/supervision-annotator-examples/trace-annotator-example-purple.png){ align=center width="800" }
+    ![trace-annotator-example](https://media.roboflow.com/supervision-annotator-examples/
+    trace-annotator-example-purple.png){ align=center width="800" }

    </div>

@@ -458,7 +475,8 @@ Annotators accept detections and apply box or mask visualizations to the detecti

    <div class="result" markdown>

-    ![heat-map-annotator-example](https://media.roboflow.com/supervision-annotator-examples/heat-map-annotator-example-purple.png){ align=center width="800" }
+    ![heat-map-annotator-example](https://media.roboflow.com/supervision-annotator-examples/
+    heat-map-annotator-example-purple.png){ align=center width="800" }

    </div>

@@ -479,7 +497,31 @@ Annotators accept detections and apply box or mask visualizations to the detecti

    <div class="result" markdown>

-    ![background-overlay-annotator-example](https://media.roboflow.com/supervision-annotator-examples/background-color-annotator-example-purple.png)
+    ![background-overlay-annotator-example](https://media.roboflow.com/supervision-annotator-examples/background-color-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Comparison"
+
+    ```python
+    import supervision as sv
+
+    image = ...
+    detections_1 = sv.Detections(...)
+    detections_2 = sv.Detections(...)
+
+    comparison_annotator = sv.ComparisonAnnotator()
+    annotated_frame = comparison_annotator.annotate(
+        scene=image.copy(),
+        detections_1=detections_1,
+        detections_2=detections_2
+    )
+    ```
+
+    <div class="result" markdown>
+
+    ![comparison-annotator-example](https://media.roboflow.com/supervision-annotator-examples/
+    comparison-annotator-example.png){ align=center width="800" }

    </div>

@@ -622,6 +664,12 @@ Annotators accept detections and apply box or mask visualizations to the detecti

 :::supervision.annotators.core.BackgroundOverlayAnnotator

+<div class="md-typeset">
+    <h2><a href="#supervision.annotators.core.ComparisonAnnotator">ComparisonAnnotator</a></h2>
+</div>
+
+:::supervision.annotators.core.ComparisonAnnotator
+
 <div class="md-typeset">
    <h2><a href="#supervision.annotators.core.ColorLookup">ColorLookup</a></h2>
 </div>
@@ -0,0 +1,441 @@
+---
+comments: true
+status: new
+---
+
+![Corgi Example](https://media.roboflow.com/supervision/image-examples/how-to/benchmark-models/corgi-sorted-2.png)
+
+# Benchmark a Model
+
+Have you ever trained multiple detection models and wondered which one performs best on your specific use case? Or maybe you've downloaded a pre-trained model and want to verify its performance on your dataset? Model benchmarking is essential for making informed decisions about which model to deploy in production.
+
+This guide will show an easy way to benchmark your results using `supervision`. It will go over:
+
+1. [Loading a dataset](#loading-a-dataset)
+2. [Loading a model](#loading-a-model)
+3. [Benchmarking Basics](#benchmarking-basics)
+4. [Running a Model](#running-a-model)
+5. [Remapping Classes](#remapping-classes)
+6. [Visual Benchmarking](#visual-benchmarking)
+7. [Benchmarking Metrics](#benchmarking-metrics)
+8. [Mean Average Precision (mAP)](#mean-average-precision-map)
+9. [F1 Score](#f1-score)
+10. [Bonus: Model Leaderboard](#model-leaderboard)
+
+This guide will use an instance segmentation model, but it applies to object detection, instance segmentation, and oriented bounding box models (OBB) too.
+
+A condensed version of this guide is available as a [Colab Notebook](https://colab.research.google.com/drive/1HoOY9pZoVwGiRMmLHtir0qT6Uj45w6Ps?usp=sharing).
+
+## Loading a Dataset
+
+Suppose you start with a dataset. Perhaps you found it on [Universe](https://universe.roboflow.com/); perhaps you [labeled your own](https://roboflow.com/how-to-label/yolo11). In either case, this guide assumes you know of a labelled dataset at hand.
+
+We'll use the following libraries:
+
+- `roboflow` to manage the dataset and deploy models
+- `inference` to run the models
+- `supervision` to evaluate the model results
+
+```bash
+pip install roboflow supervision
+pip install git+https://github.com/roboflow/inference.git@linas/allow-latest-rc-supervision
+```
+
+!!! info
+
+    We're updating `inference` at the moment. Please install it as shown above.
+
+Here's how you can download a dataset:
+
+```python
+from roboflow import Roboflow
+
+rf = Roboflow(api_key="<YOUR_API_KEY>")
+project = rf.workspace("<WORKSPACE_NAME>").project("<PROJECT_NAME>")
+dataset = project.version(<DATASET_VERSION_NUMBER>).download("<FORMAT>")
+```
+
+If your dataset is from Universe, go to `Dataset` > `Download Dataset` > select the format (e.g. `YOLOv11`) > `Show download code`.
+
+If labeling your own data, go to the [dashboard](https://app.roboflow.com/) and check this [guide](https://docs.roboflow.com/api-reference/workspace-and-project-ids) to find your workspace and project IDs.
+
+In this guide, we shall use a small [Corgi v2](https://universe.roboflow.com/model-examples/segmented-animals-basic) dataset. It is well-labeled and comes with a test set.
+
+```python
+from roboflow import Roboflow
+
+rf = Roboflow(api_key="<YOUR_API_KEY>")
+project = rf.workspace("fbamse1-gm2os").project("corgi-v2")
+dataset = project.version(4).download("yolov11")
+```
+
+This will create a folder called `Corgi-v2-4` with the dataset in the current working directory, with `train`, `test`, and `valid` folders and a `data.yaml` file.
+
+## Loading a Model
+
+Let's load a model.
+
+=== "Inference, Local"
+
+    Roboflow supports a range of state-of-the-art [pre-trained models](https://inference.roboflow.com/quickstart/aliases/) for object detection, instance segmentation, and pose tracking. You don't even need an API key!
+
+    Let's load such a model with inference [`inference`](https://inference.roboflow.com/).
+
+    ```python
+    from inference import get_model
+
+    model = get_model(model_id="yolov11s-seg-640")
+    ```
+
+=== "Inference, Deployed"
+
+    You can train and deploy a model without leaving the Roboflow platform. See this [guide](https://docs.roboflow.com/train/train/train-from-scratch) for more details.
+
+    To load a model, you can use inference:
+
+    ```python
+    from inference import get_model
+
+    model_id = "<PROJECT_NAME>/<MODEL_VERSION>"
+    model = get_model(model_id=model_id)
+    ```
+
+=== "Ultralytics"
+
+    Similarly to Inference, Ultralytics allows you to run a variety of models.
+
+    ```bash
+    pip install "ultralytics<=8.3.40"
+    ```
+
+    ```python
+    from ultralytics import YOLO
+
+    model = YOLO("yolo11s-seg.pt")
+    ```
+
+## Benchmarking Basics
+
+Evaluating your model requires careful selection of the dataset. Which images should you use?Let's go over the different scenarios.
+
+- **Unrelated Dataset**: If you have a dataset that was not used to train the model, this is the best choice.
+- **Training Set**: This is the set of images used to train the model. This is fine if the model was not trained on this dataset. Otherwise, **never** use it for benchmarking - the results will seem unrealistically good.
+- **Validation Set**: This is the set of images used to validate the model during training. Every Nth training epoch, the model is evaluated on the validation set. Often the training is stopped once the validation loss stops improving. Therefore, even while the images aren't used to train the model, it still indirectly influences the training outcome.
+- **Test Set**: This is the set of images kept aside for model testing. It is exactly the set you should use for benchmarking. If the dataset was split correctly, none of these images would be shown to the model during training.
+
+Therefore, an unrelated dataset or the `test` set is the best choice for benchmarking.
+Several other problems may arise:
+
+- **Extra Classes**: An unrelated dataset may contain additional classes which you may need to [filter out](https://supervision.roboflow.com/how_to/filter_detections/#by-set-of-classes) before computing metrics.
+- **Class Mismatch**: In an unrelated dataset, the class names or IDs may be different to what your model produces, you'll need to remap them, which is [shown in this guide](#running-a-model).
+- **Data Contamination**: The `test` set may not be split correctly, with images from the test set also present in `training` or `validation` set and used during training. In this case, the results will be overly optimistic. This also applies when **very similar** images are used for training and testing - e.g. those taken in the same environment, same lighting conditions, similar angle, etc.
+- **Missing Test Set**: Some datasets do not come with a test set. In this case, you should collect and [label](https://roboflow.com/annotate) your own data. Alternatively, a validation set could be used, but the results could be overly optimistic. Make sure to test in the real world as soon as possible.
+
+## Running a Model
+
+At this stage, you should have:
+
+- A dataset of labeled images to evaluate the model.
+- A model prepared for benchmarking.
+
+With these ready, we can now run the model and obtain predictions.
+We'll use `supervision` to create a dataset iterator, and then run the model on each image.
+
+=== "Inference"
+
+    ```python
+    import supervision as sv
+
+    test_set = sv.DetectionDataset.from_yolo(
+        images_directory_path=f"{dataset.location}/test/images",
+        annotations_directory_path=f"{dataset.location}/test/labels",
+        data_yaml_path=f"{dataset.location}/data.yaml"
+    )
+
+    image_paths = []
+    predictions_list = []
+    targets_list = []
+
+    for image_path, image, label in test_set:
+        result = model.infer(image)[0]
+        predictions = sv.Detections.from_inference(result)
+
+        image_paths.append(image_path)
+        predictions_list.append(predictions)
+        targets_list.append(label)
+    ```
+
+=== "Ultralytics"
+
+    ```python
+    import supervision as sv
+
+    test_set = sv.DetectionDataset.from_yolo(
+        images_directory_path=f"{dataset.location}/test/images",
+        annotations_directory_path=f"{dataset.location}/test/labels",
+        data_yaml_path=f"{dataset.location}/data.yaml"
+    )
+
+    image_paths = []
+    predictions_list = []
+    targets_list = []
+
+    for image_path, image, label in test_set:
+        result = model(image)[0]
+        predictions = sv.Detections.from_ultralytics(result)
+
+        image_paths.append(image_path)
+        predictions_list.append(predictions)
+        targets_list.append(label)
+    ```
+
+## Remapping classes
+
+Did you notice an issue in the above logic?
+Since we're using an unrelated dataset, the class names and IDs may be different from what the model was trained on.
+
+We need to remap them to match the dataset classes. Here's how to do it:
+
+```python
+def remap_classes(
+    detections: sv.Detections,
+    class_ids_from_to: dict[int, int],
+    class_names_from_to: dict[str, str]
+) -> None:
+    new_class_ids = [
+        class_ids_from_to.get(class_id, class_id) for class_id in detections.class_id]
+    detections.class_id = np.array(new_class_ids)
+
+    new_class_names = [
+        class_names_from_to.get(name, name) for name in detections["class_name"]]
+    predictions["class_name"] = np.array(new_class_names)
+```
+
+Let's also remove the predictions that are not in the dataset classes.
+
+=== "Inference"
+
+    Dataset class names and IDs can be found in the `data.yaml` file, or by printing `dataset.classes`.
+
+    ```python
+    import supervision as sv
+
+    test_set = sv.DetectionDataset.from_yolo(
+        images_directory_path=f"{dataset.location}/test/images",
+        annotations_directory_path=f"{dataset.location}/test/labels",
+        data_yaml_path=f"{dataset.location}/data.yaml"
+    )
+
+    image_paths = []
+    predictions_list = []
+    targets_list = []
+
+    for image_path, image, label in test_set:
+        result = model.infer(image)[0]
+        predictions = sv.Detections.from_inference(result)
+
+        remap_classes(
+            detections=predictions,
+            class_ids_from_to={16: 0},
+            class_names_from_to={"dog": "Corgi"}
+        )
+        predictions = predictions[
+            np.isin(predictions["class_name"], test_set.classes)
+        ]
+
+        image_paths.append(image_path)
+        predictions_list.append(predictions)
+        targets_list.append(label)
+    ```
+
+=== "Ultralytics"
+
+    Dataset class names and IDs can be found in the `data.yaml` file, or by printing `dataset.classes`.
+
+    Each model will have a different class mapping, so make sure to check the model's documentation. In this case, the model was trained on the COCO dataset, with a class
+    configuration found [here](https://github.com/ultralytics/ultralytics/blob/main/ultralytics/cfg/datasets/coco8.yaml).
+
+    ```python
+    import supervision as sv
+
+    test_set = sv.DetectionDataset.from_yolo(
+        images_directory_path=f"{dataset.location}/test/images",
+        annotations_directory_path=f"{dataset.location}/test/labels",
+        data_yaml_path=f"{dataset.location}/data.yaml"
+    )
+
+    image_paths = []
+    predictions_list = []
+    targets_list = []
+
+    for image_path, image, label in test_set:
+        result = model(image)[0]
+        predictions = sv.Detections.from_ultralytics(result)
+
+        remap_classes(
+            detections=predictions,
+            class_ids_from_to={16: 0},
+            class_names_from_to={"dog": "Corgi"}
+        )
+        predictions = predictions[
+            np.isin(predictions["class_name"], test_set.classes)
+        ]
+
+        image_paths.append(image_path)
+        predictions_list.append(predictions)
+        targets_list.append(label)
+    ```
+
+## Visualizing Predictions
+
+The first step in evaluating your model’s performance is to visualize its predictions.
+This gives an intuitive sense of how well your model is detecting objects and where it might be failing.
+
+```python
+import supervision as sv
+
+N = 9
+GRID_SIZE = (3, 3)
+
+target_annotator = sv.PolygonAnnotator(color=sv.Color.from_hex("#8315f9"), thickness=8)
+prediction_annotator = sv.PolygonAnnotator(color=sv.Color.from_hex("#00cfc6"), thickness=6)
+
+
+annotated_images = []
+for image_path, predictions, targets in zip(
+  image_paths[:N], predictions_list[:N], targets_list[:N]
+):
+    annotated_image = cv2.imread(image_path)
+    annotated_image = target_annotator.annotate(scene=annotated_image, detections=targets)
+    annotated_image = prediction_annotator.annotate(scene=annotated_image, detections=prediction)
+    annotated_images.append(annotated_image)
+
+sv.plot_images_grid(images=annotated_images, grid_size=GRID_SIZE)
+```
+
+Here, predictions in purple are targets (ground truth), and predictions in teal are model predictions.
+
+![Basic Model Comparison](https://media.roboflow.com/supervision/image-examples/how-to/benchmark-models/basic-model-comparison-corgi.png)
+
+!!! tip
+
+    Use `sv.BoxAnnotator` for object detection and `sv.OrientedBoxAnnotator` for OBB.
+
+    See [annotator documentation](https://supervision.roboflow.com/latest/detection/annotators/) for even more options.
+
+## Benchmarking Metrics
+
+With multiple models, fine details matter. Visual inspection may not be enough. `supervision` provides a collection of metrics that help obtain precise numerical results of model performance.
+
+### Mean Average Precision (mAP)
+
+We'll start with [MeanAveragePrecision (mAP)](https://supervision.roboflow.com/latest/metrics/mean_average_precision/#supervision.metrics.mean_average_precision.MeanAveragePrecision), which is the most commonly used metric for object detection. It measures the average precision across all classes and IoU thresholds.
+
+For a thorough explanation, check out our [blog](https://blog.roboflow.com/mean-average-precision/) and [Youtube video](https://www.youtube.com/watch?v=oqXDdxF_Wuw).
+
+Here, the most popular value is `mAP 50:95`. It represents the average precision across all classes and IoU thresholds (`0.5` to `0.95`), whereas other values such as `mAP 50` or `mAP 75` only consider a single IoU threshold (`0.5` and `0.75` respectively).
+
+Let's compute the mAP:
+
+```python
+from supervision.metrics import MeanAveragePrecision, MetricTarget
+
+map_metric = MeanAveragePrecision(metric_target=MetricTarget.MASKS)
+map_result = map_metric.update(predictions_list, targets_list).compute()
+```
+
+Try printing the result to see it at a glance:
+
+```python
+print(map_result)
+```
+
+```
+MeanAveragePrecisionResult:
+Metric target: MetricTarget.MASKS
+Class agnostic: False
+mAP @ 50:95: 0.2409
+mAP @ 50:    0.3591
+mAP @ 75:    0.2915
+mAP scores: [0.35909 0.3468 0.34556 ...]
+IoU thresh: [0.5 0.55 0.6 ...]
+AP per class:
+  0: [0.35909 0.3468 0.34556 ...]
+...
+Small objects: ...
+Medium objects: ...
+Large objects: ...
+```
+
+You can also plot the results:
+
+```python
+map_result.plot()
+```
+
+![mAP Plot](https://media.roboflow.com/supervision/image-examples/how-to/benchmark-models/mAP-plot-corgi.png)
+
+The metric also breaks down the results by detected object area. Small, medium and large are simply those with area less than 32², between 32² and 96², and greater than 96² pixels respectively.
+
+### F1 Score
+
+The [F1 Score](https://supervision.roboflow.com/latest/metrics/f1_score/) is another useful metric, especially when dealing with an imbalance between false positives and false negatives. It’s the harmonic mean of **precision** (how many predictions are correct) and **recall** (how many actual instances were detected).
+
+Here's how you can compute the F1 score:
+
+```python
+from supervision.metrics import F1Score, MetricTarget
+
+f1_metric = F1Score(metric_target=MetricTarget.MASKS)
+f1_result = f1_metric.update(predictions_list, targets_list).compute()
+```
+
+As with mAP, you can also print the result:
+
+```python
+print(f1_result)
+```
+
+```
+F1ScoreResult:
+Metric target: MetricTarget.MASKS
+Averaging method: AveragingMethod.WEIGHTED
+F1 @ 50:     0.5341
+F1 @ 75:     0.4636
+F1 @ thresh: [0.53406 0.5278 0.52153 ...]
+IoU thresh: [0.5 0.55 0.6 ...]
+F1 per class:
+  0: [0.53406 0.5278 0.52153 ...]
+...
+Small objects: ...
+Medium objects: ...
+Large objects: ...
+```
+
+Similarly, you can plot the results:
+
+```python
+f1_result.plot()
+```
+
+![F1 Plot](https://media.roboflow.com/supervision/image-examples/how-to/benchmark-models/f1-score-corgi.png)
+
+As with mAP, the metric also breaks down the results by detected object area. Small, medium and large are simply those with area less than 32², between 32² and 96², and greater than 96² pixels respectively.
+
+## Model Leaderboard
+
+Here to compare the basic models? We've got you covered. Check out our [Model Leaderboard](https://leaderboard.roboflow.com/) to see how different models perform and to get a sense of the state-of-the-art results. It's a great place to understand what the leading models can achieve and to compare your own results.
+
+Even better, the repository is open source! You can see how the models were benchmarked, run the evaluation yourself, and even add your own models to the leaderboard. Check it out on [GitHub](https://github.com/roboflow/model-leaderboard)!
+
+![Model Leaderboard Example](https://media.roboflow.com/model-leaderboard/model-leaderboard-example.png)
+
+## Conclusion
+
+In this guide, you've learned how to set up your environment, train or use pre-trained models, visualize predictions, and evaluate model performance with metrics like [mAP](https://supervision.roboflow.com/latest/metrics/mean_average_precision/), [F1 score](https://supervision.roboflow.com/latest/metrics/f1_score/), and got to know our Model Leaderboard.
+
+A condensed version of this guide is also available as a [Colab Notebook](https://colab.research.google.com/drive/1HoOY9pZoVwGiRMmLHtir0qT6Uj45w6Ps?usp=sharing).
+
+For more details, be sure to check out our [documentation](https://supervision.roboflow.com/latest/) and join our community discussions. If you find any issues, please let us know on [GitHub](https://github.com/roboflow/supervision/issues).
+
+Best of luck with your benchmarking!
@@ -33,8 +33,9 @@ We write your reusable computer vision tools. Whether you need to load your data
 You can install `supervision` in a
 [**Python>=3.8**](https://www.python.org/) environment.

-!!! example "pip install (recommended)"
-    === "pip"
+!!! example "Installation"
+
+    === "pip (recommended)"
        [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
        [![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision)
        [![license](https://img.shields.io/pypi/l/supervision)](https://github.com/roboflow/supervision/blob/main/LICENSE.md)
@@ -44,6 +45,43 @@ You can install `supervision` in a
        pip install supervision
        ```

+    === "poetry"
+        [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
+        [![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision)
+        [![license](https://img.shields.io/pypi/l/supervision)](https://github.com/roboflow/supervision/blob/main/LICENSE.md)
+        [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
+
+        ```bash
+        poetry add supervision
+        ```
+
+    === "uv"
+        [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
+        [![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision)
+        [![license](https://img.shields.io/pypi/l/supervision)](https://github.com/roboflow/supervision/blob/main/LICENSE.md)
+        [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
+
+        ```bash
+        uv pip install supervision
+        ```
+
+        For uv projects:
+
+        ```bash
+        uv add supervision
+        ```
+
+    === "rye"
+        [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
+        [![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision)
+        [![license](https://img.shields.io/pypi/l/supervision)](https://github.com/roboflow/supervision/blob/main/LICENSE.md)
+        [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
+
+        ```bash
+        rye add supervision
+        ```
+
+
 !!! example "conda/mamba install"
    === "conda"
        [![conda-recipe](https://img.shields.io/badge/recipe-supervision-green.svg)](https://anaconda.org/conda-forge/supervision) [![conda-downloads](https://img.shields.io/conda/dn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision) [![conda-version](https://img.shields.io/conda/vn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision) [![conda-platforms](https://img.shields.io/conda/pn/conda-forge/supervision.svg)](https://anaconda.org/conda-forge/supervision)
@@ -63,7 +101,7 @@ You can install `supervision` in a
    === "virtualenv"
        ```bash
        # clone repository and navigate to root directory
-        git clone https://github.com/roboflow/supervision.git
+        git clone --depth 1 -b develop https://github.com/roboflow/supervision.git
        cd supervision

        # setup python environment and activate it
@@ -78,7 +116,7 @@ You can install `supervision` in a
    === "poetry"
        ```bash
        # clone repository and navigate to root directory
-        git clone https://github.com/roboflow/supervision.git
+        git clone --depth 1 -b develop https://github.com/roboflow/supervision.git
        cd supervision

        # setup python environment and activate it
@@ -130,7 +130,7 @@
            },
            "outputs": [],
            "source": [
-                "!pip install -q ultralytics supervision==0.18.0"
+                "!pip install -q \"ultralytics<=8.3.40\" \"supervision==0.18.0\""
            ]
        },
        {
@@ -300,7 +300,7 @@
            },
            "outputs": [],
            "source": [
-                "!pip install -q ultralytics"
+                "!pip install -q \"ultralytics<=8.3.40\""
            ]
        },
        {
@@ -17,7 +17,7 @@ https://github.com/roboflow/supervision/assets/26109316/f84db7b5-79e2-4142-a1da-
 - clone repository and navigate to example directory

    ```bash
-    git clone https://github.com/roboflow/supervision.git
+    git clone --depth 1 -b develop https://github.com/roboflow/supervision.git
    cd supervision/examples/count_people_in_zone
    ```

@@ -2,4 +2,4 @@ gdown
 inference==0.9.17
 supervision>=0.20.0
 tqdm
-ultralytics
+ultralytics<=8.3.40
@@ -11,7 +11,7 @@ supervision package for multiple tasks such as drawing heatmap annotations, trac
 - clone repository and navigate to example directory

    ```bash
-    git clone https://github.com/roboflow/supervision.git
+    git clone --depth 1 -b develop https://github.com/roboflow/supervision.git
    cd supervision/examples/heatmap_and_track
    ```

@@ -1,2 +1,2 @@
 supervision[assets]==0.19.0
-ultralytics
+ultralytics<=8.3.40
@@ -22,7 +22,7 @@ https://github.com/roboflow/supervision/assets/26109316/d50118c1-2ae4-458d-915a-
 - clone repository and navigate to example directory

    ```bash
-    git clone https://github.com/roboflow/supervision.git
+    git clone --depth 1 -b develop https://github.com/roboflow/supervision.git
    cd supervision/examples/speed_estimation
    ```

@@ -16,7 +16,7 @@ https://github.com/roboflow/supervision/assets/26109316/d051cc8a-dd15-41d4-aa36-
 - clone repository and navigate to example directory

    ```bash
-    git clone https://github.com/roboflow/supervision.git
+    git clone --depth 1 -b develop https://github.com/roboflow/supervision.git
    cd supervision/examples/time_in_zone
    ```

@@ -1,5 +1,5 @@
 opencv-python
 supervision>=0.20.0
-ultralytics
+ultralytics<=8.3.40
 inference==0.9.17
 pytube
@@ -10,7 +10,7 @@ detection and Supervision for tracking and annotation.
 - clone repository and navigate to example directory

    ```bash
-    git clone https://github.com/roboflow/supervision.git
+    git clone --depth 1 -b develop https://github.com/roboflow/supervision.git
    cd supervision/examples/tracking
    ```

@@ -1,4 +1,4 @@
 inference==0.9.17
 supervision==0.19.0
 tqdm
-ultralytics
+ultralytics<=8.3.40
@@ -13,7 +13,7 @@ https://github.com/roboflow/supervision/assets/26109316/c9436828-9fbf-4c25-ae8c-
 - clone repository and navigate to example directory

    ```bash
-    git clone https://github.com/roboflow/supervision.git
+    git clone --depth 1 -b develop https://github.com/roboflow/supervision.git
    cd supervision/examples/traffic_analysis
    ```

@@ -2,4 +2,4 @@ gdown
 inference==0.9.17
 supervision>=0.20.0
 tqdm
-ultralytics
+ultralytics<=8.3.40
@@ -42,6 +42,7 @@ nav:
      - Detect Small Objects: how_to/detect_small_objects.md
      - Track Objects on Video: how_to/track_objects.md
      - Process Datasets: how_to/process_datasets.md
+      - Benchmark a Model: how_to/benchmark_a_model.md

  - Reference - Code API:
      - Detection and Segmentation:
@@ -177,8 +178,8 @@ markdown_extensions:
      anchor_linenums: true

 extra_javascript:
-  - "https://widget.kapa.ai/kapa-widget.bundle.js"
-  - "javascripts/init_kapa_widget.js"
+  # disabled until 0.27.0, so we can test its functionality
+  # - "javascripts/init_kapa_widget.js"
  - "javascripts/cookbooks-card.js"
  - "https://cdnjs.cloudflare.com/ajax/libs/dompurify/3.0.8/purify.min.js"

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "supervision"
-version = "0.25.0"
+version = "0.26.0rc2"
 description = "A set of easy-to-use utils that will come in handy in any Computer Vision project"
 authors = ["Piotr Skalski <piotr.skalski92@gmail.com>"]
 maintainers = [
@@ -43,11 +43,14 @@ classifiers = [

 [tool.poetry.dependencies]
 python = "^3.8"
+
+# For Python versions 3.13 and above, use numpy versions 2.1.0,
+# required for poetry to not fail.
 numpy = [
-    { version = ">=1.21.2,<1.23.3", python = "<=3.10" },
-    { version = ">=1.23.3", python = ">3.10" },
+    { version = ">=1.21.2", python = "<3.13" },
    { version = ">=2.1.0", python = ">=3.13" },
 ]
+
 scipy = [
    { version = "1.10.0", python = "<3.9" },
    { version = "^1.10.0", python = ">=3.9" },
@@ -62,27 +65,42 @@ scipy = [
 # For Python 3.8 and above, we use version 1.0.7 or higher, as it is the lowest major version that supports Python 3.8.
 # For Python 3.13 and above, we use version 1.3.0 or higher, as it is the first version that explicitly supports Python 3.13.
 contourpy = [
-    { version = ">=1.0.7", python = ">=3.8" },
+    { version = ">=1.0.7", python = ">=3.8,<3.13" },
    { version = ">=1.3.0", python = ">=3.13" },
 ]

-matplotlib = ">=3.6.0"
+matplotlib = [
+    { version = ">=3.6.0,<3.8.0", python = "3.8" },
+    { version = ">=3.6.0", python = ">=3.9" },
+    { version = ">=3.7.3", python = ">=3.12" },
+    { version = ">=3.9.2", python = ">=3.13" },
+]
+
+
 pyyaml = ">=5.3"
 defusedxml = "^0.7.1"
 pillow = ">=9.4"
-requests = { version = ">=2.26.0,<=2.32.3", optional = true }
-tqdm = { version = ">=4.62.3,<=4.67.0", optional = true }
+requests = ">=2.26.0"
+tqdm = ">=4.62.3"
 # pandas: picked lowest major version that supports Python 3.8
-pandas = { version = ">=2.0.0", optional = true }
-pandas-stubs = { version = ">=2.0.0.230412", optional = true }
+# pandas 2.2.3 has been released with support for Python 3.13
+pandas = [
+    { version = ">=2.0.0", python = "<3.13", optional = true },
+    { version = ">=2.2.3", python = ">=3.13", optional = true },
+]
+
 opencv-python = ">=4.5.5.64"

 [tool.poetry.extras]
-assets = ["requests", "tqdm"]
-metrics = ["pandas", "pandas-stubs"]
+metrics = ["pandas"]
+
+[tool.poetry.group.test.dependencies]
+pytest = ">=7.2.2,<9.0.0"
+pytest-md = "^0.2.0"
+pytest-emoji = "^0.2.0"

 [tool.poetry.group.dev.dependencies]
-twine = "^5.1.1"
+twine = ">=5.1.1,<7.0.0"
 pytest = ">=7.2.2,<9.0.0"
 wheel = ">=0.40,<0.46"
 build = ">=0.10,<1.3"
@@ -105,7 +123,7 @@ 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
+# Use Latest mkdocs-jupyter min 0.24.6 for Jupyter Notebook Theme support
 mkdocs-jupyter = "^0.24.3"
 mkdocs-git-committers-plugin-2 = "^2.4.1"
 mkdocs-git-revision-date-localized-plugin = "^1.2.4"
@@ -118,7 +136,10 @@ types-pyyaml = "^6.0.12.20240808"
 types-cffi = "^1.16.0.20240331"
 types-requests = "^2.32.0.20240712"
 types-tqdm = "^4.66.0.20240417"
+pandas-stubs = ">=2.0.0.230412"

+[tool.poetry.group.build.dependencies]
+twine = ">=5.1.1,<7.0.0"

 [tool.bandit]
 target = ["test", "supervision"]
@@ -14,6 +14,7 @@ from supervision.annotators.core import (
    BoxCornerAnnotator,
    CircleAnnotator,
    ColorAnnotator,
+    ComparisonAnnotator,
    CropAnnotator,
    DotAnnotator,
    EllipseAnnotator,
@@ -76,6 +77,7 @@ from supervision.detection.utils import (
    scale_boxes,
    xcycwh_to_xyxy,
    xywh_to_xyxy,
+    xyxy_to_polygons,
 )
 from supervision.draw.color import Color, ColorPalette
 from supervision.draw.utils import (
@@ -118,3 +120,110 @@ from supervision.utils.video import (
    get_video_frames_generator,
    process_video,
 )
+
+__all__ = [
+    "LMM",
+    "BackgroundOverlayAnnotator",
+    "BaseDataset",
+    "BlurAnnotator",
+    "BoundingBoxAnnotator",
+    "BoxAnnotator",
+    "BoxCornerAnnotator",
+    "ByteTrack",
+    "CSVSink",
+    "CircleAnnotator",
+    "ClassificationDataset",
+    "Classifications",
+    "Color",
+    "ColorAnnotator",
+    "ColorLookup",
+    "ColorPalette",
+    "ComparisonAnnotator",
+    "ConfusionMatrix",
+    "CropAnnotator",
+    "DetectionDataset",
+    "Detections",
+    "DetectionsSmoother",
+    "DotAnnotator",
+    "EdgeAnnotator",
+    "EllipseAnnotator",
+    "FPSMonitor",
+    "HaloAnnotator",
+    "HeatMapAnnotator",
+    "IconAnnotator",
+    "ImageSink",
+    "InferenceSlicer",
+    "JSONSink",
+    "KeyPoints",
+    "LabelAnnotator",
+    "LineZone",
+    "LineZoneAnnotator",
+    "LineZoneAnnotatorMulticlass",
+    "MaskAnnotator",
+    "MeanAveragePrecision",
+    "OrientedBoxAnnotator",
+    "OverlapFilter",
+    "PercentageBarAnnotator",
+    "PixelateAnnotator",
+    "Point",
+    "PolygonAnnotator",
+    "PolygonZone",
+    "PolygonZoneAnnotator",
+    "Position",
+    "Rect",
+    "RichLabelAnnotator",
+    "RoundBoxAnnotator",
+    "TraceAnnotator",
+    "TriangleAnnotator",
+    "VertexAnnotator",
+    "VertexLabelAnnotator",
+    "VideoInfo",
+    "VideoSink",
+    "box_iou_batch",
+    "box_non_max_merge",
+    "box_non_max_suppression",
+    "calculate_masks_centroids",
+    "calculate_optimal_line_thickness",
+    "calculate_optimal_text_scale",
+    "clip_boxes",
+    "contains_holes",
+    "contains_multiple_segments",
+    "create_tiles",
+    "crop_image",
+    "cv2_to_pillow",
+    "draw_filled_polygon",
+    "draw_filled_rectangle",
+    "draw_image",
+    "draw_line",
+    "draw_polygon",
+    "draw_rectangle",
+    "draw_text",
+    "filter_polygons_by_area",
+    "get_polygon_center",
+    "get_video_frames_generator",
+    "letterbox_image",
+    "list_files_with_extensions",
+    "mask_iou_batch",
+    "mask_non_max_suppression",
+    "mask_to_polygons",
+    "mask_to_rle",
+    "mask_to_xyxy",
+    "move_boxes",
+    "move_masks",
+    "oriented_box_iou_batch",
+    "overlay_image",
+    "pad_boxes",
+    "pillow_to_cv2",
+    "plot_image",
+    "plot_images_grid",
+    "polygon_to_mask",
+    "polygon_to_xyxy",
+    "process_video",
+    "resize_image",
+    "rle_to_mask",
+    "scale_boxes",
+    "scale_image",
+    "xcycwh_to_xyxy",
+    "xywh_to_xyxy",
+    "xyxy_to_polygons",
+]
@@ -16,10 +16,16 @@ from supervision.annotators.utils import (
 )
 from supervision.config import CLASS_NAME_DATA_FIELD, ORIENTED_BOX_COORDINATES
 from supervision.detection.core import Detections
-from supervision.detection.utils import clip_boxes, mask_to_polygons, spread_out_boxes
+from supervision.detection.utils import (
+    clip_boxes,
+    mask_to_polygons,
+    polygon_to_mask,
+    spread_out_boxes,
+    xyxy_to_polygons,
+)
 from supervision.draw.color import Color, ColorPalette
-from supervision.draw.utils import draw_polygon
-from supervision.geometry.core import Position
+from supervision.draw.utils import draw_polygon, draw_rounded_rectangle, draw_text
+from supervision.geometry.core import Point, Position, Rect
 from supervision.utils.conversion import (
    ensure_cv2_image_for_annotation,
    ensure_pil_image_for_annotation,
@@ -2527,6 +2533,9 @@ class CropAnnotator(BaseAnnotator):
                detections=detections
            )
            ```
+
+        ![crop-annotator-example](https://media.roboflow.com/
+        supervision-annotator-examples/crop-annotator-example.png)
        """
        assert isinstance(scene, np.ndarray)
        crops = [
@@ -2683,3 +2692,261 @@ class BackgroundOverlayAnnotator(BaseAnnotator):

        np.copyto(scene, colored_mask)
        return scene
+
+
+class ComparisonAnnotator:
+    """
+    Highlights the differences between two sets of detections.
+    Useful for comparing results from two different models, or the difference
+    between a ground truth and a prediction.
+
+    If present, uses the oriented bounding box data.
+    Otherwise, if present, uses a mask.
+    Otherwise, uses the bounding box data.
+    """
+
+    def __init__(
+        self,
+        color_1: Color = Color.RED,
+        color_2: Color = Color.GREEN,
+        color_overlap: Color = Color.BLUE,
+        *,
+        opacity: float = 0.75,
+        label_1: str = "",
+        label_2: str = "",
+        label_overlap: str = "",
+        label_scale: float = 1.0,
+    ):
+        """
+        Args:
+            color_1 (Color): Color of areas only present in the first set of
+                detections.
+            color_2 (Color): Color of areas only present in the second set of
+                detections.
+            color_overlap (Color): Color of areas present in both sets of detections.
+            opacity (float): Annotator opacity, from `0` to `1`.
+            label_1 (str): Label for the first set of detections.
+            label_2 (str): Label for the second set of detections.
+            label_overlap (str): Label for areas present in both sets of detections.
+            label_scale (float): Controls how large the labels are.
+        """
+
+        self.color_1 = color_1
+        self.color_2 = color_2
+        self.color_overlap = color_overlap
+
+        self.opacity = opacity
+        self.label_1 = label_1
+        self.label_2 = label_2
+        self.label_overlap = label_overlap
+        self.label_scale = label_scale
+        self.text_thickness = int(self.label_scale + 1.2)
+
+    @ensure_cv2_image_for_annotation
+    def annotate(
+        self, scene: ImageType, detections_1: Detections, detections_2: Detections
+    ) -> ImageType:
+        """
+        Highlights the differences between two sets of detections.
+
+        Args:
+            scene (ImageType): The image where detections will be drawn.
+                `ImageType` is a flexible type, accepting either `numpy.ndarray`
+                or `PIL.Image.Image`.
+            detections_1 (Detections): The first set of detections or predictions.
+            detections_2 (Detections): The second set of detections to compare or
+                ground truth.
+
+        Returns:
+            The annotated image.
+
+        Example:
+            ```python
+            import supervision as sv
+
+            image = ...
+            detections_1 = sv.Detections(...)
+            detections_2 = sv.Detections(...)
+
+            comparison_annotator = sv.ComparisonAnnotator()
+            annotated_frame = comparison_annotator.annotate(
+                scene=image.copy(),
+                detections_1=detections_1,
+                detections_2=detections_2
+            )
+            ```
+
+        ![comparison-annotator-example](https://media.roboflow.com/
+        supervision-annotator-examples/comparison-annotator-example.png)
+        """
+        assert isinstance(scene, np.ndarray)
+        if detections_1.is_empty() and detections_2.is_empty():
+            return scene
+
+        use_obb = self._use_obb(detections_1, detections_2)
+        use_mask = self._use_mask(detections_1, detections_2)
+
+        if use_obb:
+            mask_1 = self._mask_from_obb(scene, detections_1)
+            mask_2 = self._mask_from_obb(scene, detections_2)
+
+        elif use_mask:
+            mask_1 = self._mask_from_mask(scene, detections_1)
+            mask_2 = self._mask_from_mask(scene, detections_2)
+
+        else:
+            mask_1 = self._mask_from_xyxy(scene, detections_1)
+            mask_2 = self._mask_from_xyxy(scene, detections_2)
+
+        mask_overlap = mask_1 & mask_2
+        mask_1 = mask_1 & ~mask_overlap
+        mask_2 = mask_2 & ~mask_overlap
+
+        color_layer = np.zeros_like(scene, dtype=np.uint8)
+        color_layer[mask_overlap] = self.color_overlap.as_bgr()
+        color_layer[mask_1] = self.color_1.as_bgr()
+        color_layer[mask_2] = self.color_2.as_bgr()
+
+        scene[mask_overlap] = (1 - self.opacity) * scene[
+            mask_overlap
+        ] + self.opacity * color_layer[mask_overlap]
+        scene[mask_1] = (1 - self.opacity) * scene[mask_1] + self.opacity * color_layer[
+            mask_1
+        ]
+        scene[mask_2] = (1 - self.opacity) * scene[mask_2] + self.opacity * color_layer[
+            mask_2
+        ]
+
+        self._draw_labels(scene)
+
+        return scene
+
+    @staticmethod
+    def _use_obb(detections_1: Detections, detections_2: Detections) -> bool:
+        assert not detections_1.is_empty() or not detections_2.is_empty()
+        is_obb_1 = ORIENTED_BOX_COORDINATES in detections_1.data
+        is_obb_2 = ORIENTED_BOX_COORDINATES in detections_2.data
+        return (
+            (is_obb_1 and is_obb_2)
+            or (is_obb_1 and detections_2.is_empty())
+            or (detections_1.is_empty() and is_obb_2)
+        )
+
+    @staticmethod
+    def _use_mask(detections_1: Detections, detections_2: Detections) -> bool:
+        assert not detections_1.is_empty() or not detections_2.is_empty()
+        is_mask_1 = detections_1.mask is not None
+        is_mask_2 = detections_2.mask is not None
+        return (
+            (is_mask_1 and is_mask_2)
+            or (is_mask_1 and detections_2.is_empty())
+            or (detections_1.is_empty() and is_mask_2)
+        )
+
+    @staticmethod
+    def _mask_from_xyxy(scene: np.ndarray, detections: Detections) -> np.ndarray:
+        mask = np.zeros(scene.shape[:2], dtype=np.bool_)
+        if detections.is_empty():
+            return mask
+
+        resolution_wh = scene.shape[1], scene.shape[0]
+        polygons = xyxy_to_polygons(detections.xyxy)
+
+        for polygon in polygons:
+            polygon_mask = polygon_to_mask(polygon, resolution_wh=resolution_wh)
+            mask |= polygon_mask.astype(np.bool_)
+        return mask
+
+    @staticmethod
+    def _mask_from_obb(scene: np.ndarray, detections: Detections) -> np.ndarray:
+        mask = np.zeros(scene.shape[:2], dtype=np.bool_)
+        if detections.is_empty():
+            return mask
+
+        resolution_wh = scene.shape[1], scene.shape[0]
+
+        for polygon in detections.data[ORIENTED_BOX_COORDINATES]:
+            polygon_mask = polygon_to_mask(polygon, resolution_wh=resolution_wh)
+            mask |= polygon_mask.astype(np.bool_)
+        return mask
+
+    @staticmethod
+    def _mask_from_mask(scene: np.ndarray, detections: Detections) -> np.ndarray:
+        mask = np.zeros(scene.shape[:2], dtype=np.bool_)
+        if detections.is_empty():
+            return mask
+        assert detections.mask is not None
+
+        for detections_mask in detections.mask:
+            mask |= detections_mask.astype(np.bool_)
+        return mask
+
+    def _draw_labels(self, scene: np.ndarray) -> None:
+        """
+        Draw the labels, explaining what each color represents, with automatically
+        computed positions.
+
+        Args:
+            scene (np.ndarray): The image where the labels will be drawn.
+        """
+        margin = int(50 * self.label_scale)
+        gap = int(40 * self.label_scale)
+        y0 = int(50 * self.label_scale)
+        height = int(50 * self.label_scale)
+
+        marker_size = int(20 * self.label_scale)
+        padding = int(10 * self.label_scale)
+        text_box_corner_radius = int(10 * self.label_scale)
+        marker_corner_radius = int(4 * self.label_scale)
+        text_scale = self.label_scale
+
+        label_color_pairs = [
+            (self.label_1, self.color_1),
+            (self.label_2, self.color_2),
+            (self.label_overlap, self.color_overlap),
+        ]
+
+        x0 = margin
+        for text, color in label_color_pairs:
+            if not text:
+                continue
+
+            (text_w, _) = cv2.getTextSize(
+                text=text,
+                fontFace=CV2_FONT,
+                fontScale=self.label_scale,
+                thickness=self.text_thickness,
+            )[0]
+
+            width = text_w + marker_size + padding * 4
+            center_x = x0 + width // 2
+            center_y = y0 + height // 2
+
+            draw_rounded_rectangle(
+                scene=scene,
+                rect=Rect(x=x0, y=y0, width=width, height=height),
+                color=Color.WHITE,
+                border_radius=text_box_corner_radius,
+            )
+
+            draw_rounded_rectangle(
+                scene=scene,
+                rect=Rect(
+                    x=x0 + padding,
+                    y=center_y - marker_size / 2,
+                    width=marker_size,
+                    height=marker_size,
+                ),
+                color=color,
+                border_radius=marker_corner_radius,
+            )
+
+            draw_text(
+                scene,
+                text,
+                text_anchor=Point(x=center_x + marker_size, y=center_y),
+                text_scale=text_scale,
+                text_thickness=self.text_thickness,
+            )
+
+            x0 += width + gap
@@ -1,2 +1,4 @@
 from supervision.assets.downloader import download_assets
 from supervision.assets.list import VideoAssets
+
+__all__ = ["VideoAssets", "download_assets"]
@@ -4,19 +4,10 @@ from pathlib import Path
 from shutil import copyfileobj
 from typing import Union

-from supervision.assets.list import VIDEO_ASSETS, VideoAssets
+from requests import get
+from tqdm.auto import tqdm

-try:
-    from requests import get
-    from tqdm.auto import tqdm
-except ImportError:
-    raise ValueError(
-        "\n"
-        "Please install requests and tqdm to download assets \n"
-        "or install supervision with assets \n"
-        "pip install supervision[assets] \n"
-        "\n"
-    )
+from supervision.assets.list import VIDEO_ASSETS, VideoAssets


 def is_md5_hash_matching(filename: str, original_md5_hash: str) -> bool:
@@ -1,6 +1,5 @@
 from __future__ import annotations

-from contextlib import suppress
 from dataclasses import dataclass, field
 from typing import Any, Dict, Iterator, List, Optional, Tuple, Union

@@ -117,7 +116,7 @@ class Detections:
        xyxy (np.ndarray): An array of shape `(n, 4)` containing
            the bounding boxes coordinates in format `[x1, y1, x2, y2]`
        mask: (Optional[np.ndarray]): An array of shape
-            `(n, H, W)` containing the segmentation masks.
+            `(n, H, W)` containing the segmentation masks (`bool` data type).
        confidence (Optional[np.ndarray]): An array of shape
            `(n,)` containing the confidence scores of the detections.
        class_id (Optional[np.ndarray]): An array of shape
@@ -606,8 +605,10 @@ class Detections:
            detections = sv.Detections.from_inference(result)
            ```
        """
-        with suppress(AttributeError):
+        if hasattr(roboflow_result, "dict"):
            roboflow_result = roboflow_result.dict(exclude_none=True, by_alias=True)
+        elif hasattr(roboflow_result, "json"):
+            roboflow_result = roboflow_result.json()
        xyxy, confidence, class_id, masks, trackers, data = process_roboflow_result(
            roboflow_result=roboflow_result
        )
@@ -1201,6 +1202,8 @@ class Detections:
        """
        if isinstance(index, str):
            return self.data.get(index)
+        if self.is_empty():
+            return Detections.empty()
        if isinstance(index, int):
            index = [index]
        return Detections(
@@ -11,6 +11,25 @@ from supervision.geometry.core import Vector
 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.

@@ -701,25 +720,71 @@ def move_masks(
        masks (npt.NDArray[np.bool_]): 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.
-        offset (npt.NDArray[np.int32]): An array of shape `(2,)` containing non-negative
-            int values `[dx, dy]`.
+        offset (npt.NDArray[np.int32]): An array of shape `(2,)` containing int values
+            `[dx, dy]`. Supports both positive and negative values for bidirectional
+            movement.
        resolution_wh (Tuple[int, int]): The width and height of the desired mask
            resolution.

    Returns:
        (npt.NDArray[np.bool_]) repositioned masks, optionally padded to the specified
            shape.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        mask = np.array([[[False, False, False, False],
+                         [False, True,  True,  False],
+                         [False, True,  True,  False],
+                         [False, False, False, False]]], dtype=bool)
+
+        offset = np.array([1, 1])
+        sv.move_masks(mask, offset, resolution_wh=(4, 4))
+        # array([[[False, False, False, False],
+        #         [False, False, False, False],
+        #         [False, False,  True,  True],
+        #         [False, False,  True,  True]]], dtype=bool)
+
+        offset = np.array([-2, 2])
+        sv.move_masks(mask, offset, resolution_wh=(4, 4))
+        # array([[[False, False, False, False],
+        #         [False, False, False, False],
+        #         [False, False, False, False],
+        #         [True,  False, False, False]]], dtype=bool)
+        ```
    """
-
-    if offset[0] < 0 or offset[1] < 0:
-        raise ValueError(f"Offset values must be non-negative integers. Got: {offset}")
-
    mask_array = np.full((masks.shape[0], resolution_wh[1], resolution_wh[0]), False)
-    mask_array[
-        :,
-        offset[1] : masks.shape[1] + offset[1],
-        offset[0] : masks.shape[2] + offset[0],
-    ] = masks
+
+    if offset[0] < 0:
+        source_x_start = -offset[0]
+        source_x_end = min(masks.shape[2], resolution_wh[0] - offset[0])
+        destination_x_start = 0
+        destination_x_end = min(resolution_wh[0], masks.shape[2] + offset[0])
+    else:
+        source_x_start = 0
+        source_x_end = min(masks.shape[2], resolution_wh[0] - offset[0])
+        destination_x_start = offset[0]
+        destination_x_end = offset[0] + source_x_end - source_x_start
+
+    if offset[1] < 0:
+        source_y_start = -offset[1]
+        source_y_end = min(masks.shape[1], resolution_wh[1] - offset[1])
+        destination_y_start = 0
+        destination_y_end = min(resolution_wh[1], masks.shape[1] + offset[1])
+    else:
+        source_y_start = 0
+        source_y_end = min(masks.shape[1], resolution_wh[1] - offset[1])
+        destination_y_start = offset[1]
+        destination_y_end = offset[1] + source_y_end - source_y_start
+
+    if source_x_end > source_x_start and source_y_end > source_y_start:
+        mask_array[
+            :,
+            destination_y_start:destination_y_end,
+            destination_x_start:destination_x_end,
+        ] = masks[:, source_y_start:source_y_end, source_x_start:source_x_end]

    return mask_array

@@ -1,6 +1,5 @@
 from __future__ import annotations

-from contextlib import suppress
 from dataclasses import dataclass, field
 from typing import Any, Dict, Iterable, Iterator, List, Optional, Tuple, Union

@@ -204,9 +203,10 @@ class KeyPoints:
                "You can retrieve it like so:  inference_result = model.infer(image)[0]"
            )

-        with suppress(AttributeError):
+        if hasattr(inference_result, "dict"):
            inference_result = inference_result.dict(exclude_none=True, by_alias=True)
-
+        elif hasattr(inference_result, "json"):
+            inference_result = inference_result.json()
        if not inference_result.get("predictions"):
            return cls.empty()

@@ -19,3 +19,22 @@ from supervision.metrics.utils.object_size import (
    get_detection_size_category,
    get_object_size_category,
 )
+
+__all__ = [
+    "AveragingMethod",
+    "F1Score",
+    "F1ScoreResult",
+    "MeanAveragePrecision",
+    "MeanAveragePrecisionResult",
+    "MeanAverageRecall",
+    "MeanAverageRecallResult",
+    "Metric",
+    "MetricTarget",
+    "ObjectSizeCategory",
+    "Precision",
+    "PrecisionResult",
+    "Recall",
+    "RecallResult",
+    "get_detection_size_category",
+    "get_object_size_category",
+]
@@ -223,6 +223,12 @@ TEST_DET_DIFFERENT_METADATA = Detections(
            None,
            pytest.raises(IndexError),
        ),
+        (
+            Detections.empty(),
+            np.isin(Detections.empty()["class_name"], ["cat", "dog"]),
+            Detections.empty(),
+            DoesNotRaise(),
+        ),  # Filter an empty detections by specific class names
    ],
 )
 def test_getitem(
@@ -16,6 +16,7 @@ from supervision.detection.utils import (
    merge_data,
    merge_metadata,
    move_boxes,
+    move_masks,
    process_roboflow_result,
    scale_boxes,
    xcycwh_to_xyxy,
@@ -442,6 +443,268 @@ def test_move_boxes(
        assert np.array_equal(result, expected_result)


+@pytest.mark.parametrize(
+    "masks, offset, resolution_wh, expected_result, exception",
+    [
+        (
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, True, True, False],
+                        [False, True, True, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            np.array([0, 0]),
+            (4, 4),
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, True, True, False],
+                        [False, True, True, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            DoesNotRaise(),
+        ),
+        (
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, True, True, False],
+                        [False, True, True, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            np.array([-1, -1]),
+            (4, 4),
+            np.array(
+                [
+                    [
+                        [True, True, False, False],
+                        [True, True, False, False],
+                        [False, False, False, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            DoesNotRaise(),
+        ),
+        (
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, True, True, False],
+                        [False, True, True, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            np.array([-2, -2]),
+            (4, 4),
+            np.array(
+                [
+                    [
+                        [True, False, False, False],
+                        [False, False, False, False],
+                        [False, False, False, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            DoesNotRaise(),
+        ),
+        (
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, True, True, False],
+                        [False, True, True, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            np.array([-3, -3]),
+            (4, 4),
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, False, False, False],
+                        [False, False, False, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            DoesNotRaise(),
+        ),
+        (
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, True, True, False],
+                        [False, True, True, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            np.array([-2, -1]),
+            (4, 4),
+            np.array(
+                [
+                    [
+                        [True, False, False, False],
+                        [True, False, False, False],
+                        [False, False, False, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            DoesNotRaise(),
+        ),
+        (
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, True, True, False],
+                        [False, True, True, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            np.array([-1, -2]),
+            (4, 4),
+            np.array(
+                [
+                    [
+                        [True, True, False, False],
+                        [False, False, False, False],
+                        [False, False, False, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            DoesNotRaise(),
+        ),
+        (
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, True, True, False],
+                        [False, True, True, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            np.array([-2, 2]),
+            (4, 4),
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, False, False, False],
+                        [False, False, False, False],
+                        [True, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            DoesNotRaise(),
+        ),
+        (
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, True, True, False],
+                        [False, True, True, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            np.array([3, 3]),
+            (4, 4),
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, False, False, False],
+                        [False, False, False, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            DoesNotRaise(),
+        ),
+        (
+            np.array(
+                [
+                    [
+                        [False, False, False, False],
+                        [False, True, True, False],
+                        [False, True, True, False],
+                        [False, False, False, False],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            np.array([3, 3]),
+            (6, 6),
+            np.array(
+                [
+                    [
+                        [False, False, False, False, False, False],
+                        [False, False, False, False, False, False],
+                        [False, False, False, False, False, False],
+                        [False, False, False, False, False, False],
+                        [False, False, False, False, True, True],
+                        [False, False, False, False, True, True],
+                    ]
+                ],
+                dtype=bool,
+            ),
+            DoesNotRaise(),
+        ),
+    ],
+)
+def test_move_masks(
+    masks: np.ndarray,
+    offset: np.ndarray,
+    resolution_wh: Tuple[int, int],
+    expected_result: np.ndarray,
+    exception: Exception,
+) -> None:
+    with exception:
+        result = move_masks(masks=masks, offset=offset, resolution_wh=resolution_wh)
+        np.testing.assert_array_equal(result, expected_result)
+
+
@pytest.mark.parametrize(
    "xyxy, factor, expected_result, exception",
    [
@@ -22,33 +22,26 @@ def mock_callback():
@pytest.mark.parametrize(
    "slice_wh, overlap_ratio_wh, overlap_wh, expected_overlap, exception",
    [
-        # Valid case: overlap_ratio_wh provided, overlap calculated from the ratio
-        ((128, 128), (0.2, 0.2), None, None, DoesNotRaise()),
-        # Valid case: overlap_wh in pixels, no ratio provided
+        # Valid case: explicit overlap_wh in pixels
+        ((128, 128), None, (26, 26), (26, 26), DoesNotRaise()),
+        # Valid case: overlap_wh in pixels
        ((128, 128), None, (20, 20), (20, 20), DoesNotRaise()),
-        # Invalid case: overlap_ratio_wh greater than 1, should raise ValueError
-        ((128, 128), (1.1, 0.5), None, None, pytest.raises(ValueError)),
        # Invalid case: negative overlap_wh, should raise ValueError
        ((128, 128), None, (-10, 20), None, pytest.raises(ValueError)),
-        # Invalid case:
-        # overlap_ratio_wh and overlap_wh provided, should raise ValueError
-        ((128, 128), (0.5, 0.5), (20, 20), (20, 20), pytest.raises(ValueError)),
-        # Valid case: no overlap_ratio_wh, overlap_wh = 50 pixels
-        ((256, 256), None, (50, 50), (50, 50), DoesNotRaise()),
-        # Valid case: overlap_ratio_wh provided, overlap calculated from (0.3, 0.3)
-        ((200, 200), (0.3, 0.3), None, None, DoesNotRaise()),
-        # Valid case: small overlap_ratio_wh values
-        ((100, 100), (0.1, 0.1), None, None, DoesNotRaise()),
-        # Invalid case: negative overlap_ratio_wh value, should raise ValueError
-        ((128, 128), (-0.1, 0.2), None, None, pytest.raises(ValueError)),
-        # Invalid case: negative overlap_ratio_wh with overlap_wh provided
-        ((128, 128), (-0.1, 0.2), (30, 30), None, pytest.raises(ValueError)),
-        # Invalid case: overlap_wh greater than slice size, should raise ValueError
-        ((128, 128), None, (150, 150), (150, 150), DoesNotRaise()),
-        # Valid case: overlap_ratio_wh is 0, no overlap
-        ((128, 128), (0.0, 0.0), None, None, DoesNotRaise()),
-        # Invalid case: no overlaps defined, no overlap
+        # Invalid case: no overlaps defined
        ((128, 128), None, None, None, pytest.raises(ValueError)),
+        # Valid case: overlap_wh = 50 pixels
+        ((256, 256), None, (50, 50), (50, 50), DoesNotRaise()),
+        # Valid case: overlap_wh = 60 pixels
+        ((200, 200), None, (60, 60), (60, 60), DoesNotRaise()),
+        # Valid case: small overlap_wh values
+        ((100, 100), None, (0.1, 0.1), (0.1, 0.1), DoesNotRaise()),
+        # Invalid case: negative overlap_wh values
+        ((128, 128), None, (-10, -10), None, pytest.raises(ValueError)),
+        # Invalid case: overlap_wh greater than slice size
+        ((128, 128), None, (150, 150), (150, 150), DoesNotRaise()),
+        # Valid case: zero overlap
+        ((128, 128), None, (0, 0), (0, 0), DoesNotRaise()),
    ],
 )
 def test_inference_slicer_overlap(