👊 bump version from 0.17.1 to 0.18.0rc1

⬆️ Bump mkdocs-material from 9.5.2 to 9.5.3

.gitattributes

@@ -1 +1 @@
-*.ipynb linguist-vendored
+*.ipynb linguist-vendored

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -62,4 +62,4 @@ body:
       description: >
         (Optional) We encourage you to submit a [Pull Request](https://github.com/roboflow/supervision/pulls) (PR) to help improve Supervision for everyone, especially if you have a good understanding of how to implement a fix or feature.
       options:
-        - label: Yes I'd like to help by submitting a PR!
+        - label: Yes I'd like to help by submitting a PR!

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -46,4 +46,4 @@ body:
       description: >
         (Optional) We encourage you to submit a [Pull Request](https://github.com/roboflow/supervision/pulls) (PR) to help improve Supervision for everyone, especially if you have a good understanding of how to implement a fix or feature.
       options:
-        - label: Yes I'd like to help by submitting a PR!
+        - label: Yes I'd like to help by submitting a PR!

.github/ISSUE_TEMPLATE/question.yml

@@ -30,4 +30,4 @@ body:
   - type: textarea
     attributes:
       label: Additional
-      description: Anything else you would like to share?
+      description: Anything else you would like to share?

.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    commit-message:
+      prefix: ⬆️
+  # Python
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    commit-message:
+      prefix: ⬆️

.github/requirements-dev-min.txt

@@ -0,0 +1,28 @@
+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
+packaging==23.2
+Pillow==10.1.0
+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.9.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

.github/workflows/clear-cache.yml

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

.github/workflows/docs.yml

@@ -6,14 +6,21 @@ on:
       - master
       - main
       - develop
+
+permissions:
+  contents: write
+  pages: write
+  pull-requests: write
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: 3.x
       - run: pip install mkdocs-material
       - run: pip install "mkdocstrings[python]"
+      - run: pip install "mkdocs-material[imaging]"
       - run: mkdocs gh-deploy --force

.github/workflows/publish-test.yml

@@ -0,0 +1,41 @@
+name: Supervision Test Releases to PyPi
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+[0-9]+.[0-9]+a[0-9]'
+      - '[0-9]+.[0-9]+[0-9]+.[0-9]+b[0-9]'
+      - '[0-9]+.[0-9]+[0-9]+.[0-9]+rc[0-9]'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build-n-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: 🐍 Set up Python 3.8 environment for build
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.8"
+
+      - name: 🏗️ Build source and wheel distributions
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          twine check --strict dist/*
+      - name: 🚀 Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: ${{ secrets.PYPI_USERNAME }}
+          password: ${{ secrets.PYPI_PASSWORD }}
+      - name: 🚀 Publish to Test-PyPi
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          user: ${{ secrets.PYPI_TEST_USERNAME }}
+          password: ${{ secrets.PYPI_TEST_PASSWORD }}

.github/workflows/publish.yml

@@ -1,8 +1,13 @@
-name: Publish WorkFlow
-
+name: Supervision Releases to PyPi
 on:
-  release:
-    types: [created]
+  push:
+    tags:
+      - '[0-9]+.[0-9]+[0-9]+.[0-9]'
+      - '[0-9]+.[0-9]+[0-9]+.[0-9]'
+      - '[0-9]+.[0-9]+[0-9]+.[0-9]'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
 
 jobs:
   build:
@@ -12,22 +17,13 @@ jobs:
         python-version: [3.8]
     steps:
       - name: 🛎️ Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           ref: ${{ github.head_ref }}
       - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - name: 🦾 Install dependencies
-        run: |
-          python -m pip install --upgrade virtualenv
-          python -m pip install --upgrade pip
-          virtualenv venv
-          source venv/bin/activate
-          python -m pip install --upgrade pip
-          python -m pip install --upgrade poetry
-          poetry install
 
       - name:  🏗️ Build source and wheel distributions
         run: |
@@ -43,5 +39,5 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           repository-url: https://test.pypi.org/legacy/
-          user: ${{ secrets.PYPI_USERNAME }}
+          user: ${{ secrets.PYPI_TEST_USERNAME }}
           password: ${{ secrets.PYPI_TEST_PASSWORD }}

.github/workflows/test-min.yml

@@ -0,0 +1,32 @@
+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
+          cache: 'pip'
+          cache-dependency-path: '**/requirements-dev-min.txt'
+
+      - name: 📦 Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r .github/requirements-dev-min.txt
+
+      - name: 🧪 Test
+        run: "python -m pytest ./test"

.github/workflows/test.yml

@@ -5,28 +5,25 @@ on:
     branches: [main, develop]
 
 jobs:
-  build:
+  build-dev-test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10","3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
       - name: 🛎️ Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - name: 🦾 Install dependencies
+          check-latest: true
+
+      - name: 📦 Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .
+          pip install .
           pip install pytest
-          pip install isort
-          pip install flake8
-          pip install "black==22.3.0"
-      - name: 🧹 Lint with flake8
-        run: |
-          make check_code_quality
+
       - name: 🧪 Test
-        run: "python -m pytest ./test"
+        run: "python -m pytest ./test"

.github/workflows/welcome.yml

@@ -11,8 +11,8 @@ jobs:
     name: 👋 Welcome
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/first-interaction@v1.1.1
+      - uses: actions/first-interaction@v1.3.0
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           issue-message: "Hello there, thank you for opening an Issue ! 🙏🏻 The team was notified and they will get back to you asap."
-          pr-message:  "Hello there, thank you for opening an PR ! 🙏🏻 The team was notified and they will get back to you asap."
+          pr-message:  "Hello there, thank you for opening an PR ! 🙏🏻 The team was notified and they will get back to you asap."

.gitignore

@@ -54,6 +54,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+.ruff_cache/
 
 # Translations
 *.mo

.pre-commit-config.yaml

@@ -0,0 +1,54 @@
+
+ci:
+  autofix_prs: true
+  autoupdate_schedule: weekly
+  autofix_commit_msg: "fix(pre_commit): 🎨 auto format pre-commit hooks"
+  autoupdate_commit_msg: "chore(pre_commit): ⬆ pre_commit autoupdate"
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        exclude: test/.*\.py
+      - id: check-yaml
+      - id: check-docstring-first
+      - id: check-executables-have-shebangs
+      - id: check-toml
+      - id: check-case-conflict
+      - id: check-added-large-files
+      - id: detect-private-key
+      - id: forbid-new-submodules
+      - id: pretty-format-json
+        exclude: demo.ipynb
+        args: ['--autofix', '--no-sort-keys', '--indent=4']
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+
+
+
+  -   repo: https://github.com/PyCQA/bandit
+      rev: '1.7.6'
+      hooks:
+      -   id: bandit
+          args: ["-c", "pyproject.toml"]
+          additional_dependencies: ["bandit[toml]"]
+
+  -   repo: https://github.com/pycqa/isort
+      rev: 5.13.2
+      hooks:
+      -   id: isort
+          name: isort (python)
+      -   id: isort
+          name: isort (pyi)
+          types: [pyi]
+
+
+  -   repo: https://github.com/astral-sh/ruff-pre-commit
+      rev: v0.1.9
+      hooks:
+      -   id: ruff
+          args: [--fix, --exit-non-zero-on-fix]
+      -   id: ruff-format
+          types_or: [ python, pyi, jupyter ]

CITATION.cff

@@ -1,12 +1,23 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
 cff-version: 1.2.0
-author: Roboflow
-message: If you use this software, please cite it as below.
-title: supervision
-version: 0.11.1
-date-released: 2023-01-19
-license: MIT
-repository-code: https://github.com/roboflow/supervision
+title: Supervision
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Roboflow
+    email: support@roboflow.com
+repository-code: 'https://github.com/roboflow/supervision'
+url: 'https://roboflow.github.io/supervision/'
+abstract: >-
+  supervision features a range of utilities for use in
+  computer vision projects, from detections processing and
+  filtering to confusion matrix calcuation.
 keywords:
   - computer vision
   - image processing
-  - video processing
+  - video processing
+license: MIT

CODE_OF_CONDUCT.md

@@ -0,0 +1,134 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+community-reports@roboflow.com.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -14,7 +14,7 @@ We welcome contributions to:
 4. Submit a request for a new feature.
 5. Improve our test coverage.
 
-### Contributing Features
+### Contributing Features ✨
 
 Supervision is designed to provide generic utilities to solve problems. Thus, we focus on contributions that can have an impact on a wide range of projects.
 
@@ -24,7 +24,71 @@ Before you contribute a new feature, consider submitting an Issue to discuss the
 
 ## How to Contribute Changes
 
-First, fork this repository to your own GitHub account. Create a new branch that describes your changes (i.e. `line-counter-docs`). Push your changes to the branch on your fork and then submit a pull request to `develop` branch of this repository.
+First, fork this repository to your own GitHub account. Click "fork" in the top corner of the `supervision` repository to get started:
+
+![Forking the repository](https://media.roboflow.com/fork.png)
+
+![Creating a repository fork](https://media.roboflow.com/create_fork.png)
+
+Then, run `git clone` to download the project code to your computer.
+
+Move to a new branch using the `git checkout` command:
+
+```bash
+git checkout -b <your_branch_name>
+```
+
+The name you choose for your branch should describe the change you want to make (i.e. `line-counter-docs`).
+
+Make any changes you want to the project code, then run the following commands to commit your changes:
+
+```bash
+git add .
+git commit -m "Your commit message"
+git push -u origin main
+```
+
+## 🎨 Code quality
+
+### Pre-commit tool
+
+This project utilizes the [pre-commit](https://pre-commit.com/) tool to maintain code quality and consistency. Before submitting a pull request or making any commits, it is important to run the pre-commit tool to ensure that your changes meet the project's guidelines.
+
+Furthermore, we have integrated a pre-commit GitHub Action into our workflow. This means that with every pull request opened, the pre-commit checks will be automatically enforced, streamlining the code review process and ensuring that all contributions adhere to our quality standards.
+
+To run the pre-commit tool, follow these steps:
+
+1. Install pre-commit by running the following command: `poetry install`. It will not only install pre-commit but also install all the deps and dev-deps of project
+
+2. Once pre-commit is installed, navigate to the project's root directory.
+
+3. Run the command `pre-commit run --all-files`. This will execute the pre-commit hooks configured for this project against the modified files. If any issues are found, the pre-commit tool will provide feedback on how to resolve them. Make the necessary changes and re-run the pre-commit command until all issues are resolved.
+
+4. You can also install pre-commit as a git hook by execute `pre-commit install`. Every time you made `git commit` pre-commit run automatically for you.
+
+### Docstrings
+
+All new functions and classes in `supervision` should include docstrings. This is a prerequisite for any new functions and classes to be added to the library.
+
+`supervision` adheres to the [Google Python docstring style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods). Please refer to the style guide while writing docstrings for your contribution.
+
+### Type checking
+
+So far, **there is no type checking with mypy**. See [issue](https://github.com/roboflow-ai/template-python/issues/4).
+
+Then, go back to your fork of the `supervision` repository, click "Pull Requests", and click "New Pull Request".
+
+![Opening a pull request](https://media.roboflow.com/open_pr.png)
+
+Make sure the `base` branch is `develop` before submitting your PR.
+
+On the next page, review your changes then click "Create pull request":
+
+![Configuring a pull request](https://media.roboflow.com/create_pr_submit.png)
+
+Next, write a description for your pull request, and click "Create pull request" again to submit it for review:
+
+![Submitting a pull request](https://media.roboflow.com/write_pr.png)
 
 When creating new functions, please ensure you have the following:
 
@@ -32,21 +96,26 @@ When creating new functions, please ensure you have the following:
 2. Unit tests for the function.
 3. Examples in the documentation for the function.
 4. Created an entry in our docs to autogenerate the documentation for the function.
-5. Please share google colab with minimal code to test new feature or reproduce PR whenever it is possible. Please ensure that google colab can be accessed without any issue. 
+5. Please share a Google Colab with minimal code to test new feature or reproduce PR whenever it is possible. Please ensure that Google Colab can be accessed without any issue.
+
+When you submit your Pull Request, you will be asked to sign a Contributor License Agreement (CLA) by the `cla-assistant` GitHub bot. We can only respond to PRs from contributors who have signed the project CLA.
 
 All pull requests will be reviewed by the maintainers of the project. We will provide feedback and ask for changes if necessary.
 
 PRs must pass all tests and linting requirements before they can be merged.
 
-## 🧹 code quality 
+## 📝 documentation
 
-We provide two handy commands inside the `Makefile`, namely:
+The `supervision` documentation is stored in a folder called `docs`. The project documentation is built using `mkdocs`.
 
-- `make style` to format the code
-- `make check_code_quality` to check code quality (PEP8 basically)
+To run the documentation, install the project requirements with `poetry install --with dev`. Then, run `mkdocs serve` to start the documentation server.
 
-So far, **there is no types checking with mypy**. See [issue](https://github.com/roboflow-ai/template-python/issues/4). 
+You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/).
 
-## 🧪 tests 
+## 🧪 tests
 
 [`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests.
+
+## 📄 license
+
+By contributing, you agree that your contributions will be licensed under an [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md).

Makefile

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

README.md

@@ -10,11 +10,17 @@
 
   <br>
 
+[notebooks](https://github.com/roboflow/notebooks) | [inference](https://github.com/roboflow/inference) | [autodistill](https://github.com/autodistill/autodistill) | [collect](https://github.com/roboflow/roboflow-collect)
+
+  <br>
+
 [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
 [![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision)
 [![license](https://img.shields.io/pypi/l/supervision)](https://github.com/roboflow/supervision/blob/main/LICENSE.md)
 [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
 [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow/supervision/blob/main/demo.ipynb)
+[![Gradio](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Roboflow/Annotators)
+[![Discord](https://img.shields.io/discord/1159501506232451173)](https://discord.gg/GbfgXGJ8Bk)
 
 </div>
 
@@ -25,76 +31,89 @@
 ## 💻 install
 
 Pip install the supervision package in a
-[**3.11>=Python>=3.8**](https://www.python.org/) environment.
+[**Python>=3.8**](https://www.python.org/) environment.
 
 ```bash
-pip install supervision[desktop]
+pip install supervision
 ```
 
 Read more about desktop, headless, and local installation in our [guide](https://roboflow.github.io/supervision/).
 
 ## 🔥 quickstart
 
-### [detections processing](https://roboflow.github.io/supervision/detection/core/)
+### models
+
+Supervision was designed to be model agnostic. Just plug in any classification, detection, or segmentation model. For your convenience, we have created [connectors](https://supervision.roboflow.com/detection/core/#detections) for the most popular libraries like Ultralytics, Transformers, or MMDetection.
 
 ```python
+>>> import cv2
 >>> import supervision as sv
 >>> from ultralytics import YOLO
 
+>>> image = cv2.imread(...)
 >>> model = YOLO('yolov8s.pt')
->>> result = model(IMAGE)[0]
->>> detections = sv.Detections.from_yolov8(result)
+>>> result = model(image)[0]
+>>> detections = sv.Detections.from_ultralytics(result)
 
 >>> len(detections)
 5
 ```
 
-<details close>
-<summary>👉 more detections utils</summary>
-  
-- Easily switch inference pipeline between supported object detection/instance segmentation models
-  
-    ```python
-    >>> import supervision as sv
-    >>> from segment_anything import sam_model_registry, SamAutomaticMaskGenerator
+<details>
+<summary>👉 more model connectors</summary>
 
-    >>> sam = sam_model_registry[MODEL_TYPE](checkpoint=CHECKPOINT_PATH).to(device=DEVICE)
-    >>> mask_generator = SamAutomaticMaskGenerator(sam)
-    >>> sam_result = mask_generator.generate(IMAGE)
-    >>> detections = sv.Detections.from_sam(sam_result=sam_result)
-    ```
- 
-- [Advanced filtering](https://roboflow.github.io/supervision/quickstart/detections/)
-  
-    ```python
-    >>> detections = detections[detections.class_id == 0]
-    >>> detections = detections[detections.confidence > 0.5]
-    >>> detections = detections[detections.area > 1000]
-    ```
-  
-- Image annotation
-  
-    ```python
-    >>> import supervision as sv
+- inference
+
+    Running with [Inference](https://github.com/roboflow/inference) requires a [Roboflow API KEY](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key).
+
+    ```python
+    >>> import cv2
+    >>> import supervision as sv
+    >>> from inference.models.utils import get_roboflow_model
+
+    >>> image = cv2.imread(...)
+    >>> model = get_roboflow_model(model_id="yolov8s-640", api_key=<ROBOFLOW API KEY>)
+    >>> result = model.infer(image)[0]
+    >>> detections = sv.Detections.from_inference(result)
+
+    >>> len(detections)
+    >>> 5
 
-    >>> box_annotator = sv.BoxAnnotator()
-    >>> annotated_frame = box_annotator.annotate(
-    ...     scene=IMAGE,
-    ...     detections=detections
-    ... )
     ```
-  
+
 </details>
 
-### [datasets processing](https://roboflow.github.io/supervision/dataset/core/)
+### annotators
+
+Supervision offers a wide range of highly customizable [annotators](https://supervision.roboflow.com/annotators/), allowing you to compose the perfect visualization for your use case.
+
+```python
+>>> import cv2
+>>> import supervision as sv
+
+>>> image = cv2.imread(...)
+>>> detections = sv.Detections(...)
+
+>>> bounding_box_annotator = sv.BoundingBoxAnnotator()
+>>> annotated_frame = bounding_box_annotator.annotate(
+...     scene=image.copy(),
+...     detections=detections
+... )
+```
+
+https://github.com/roboflow/supervision/assets/26109316/691e219c-0565-4403-9218-ab5644f39bce
+
+### datasets
+
+Supervision provides a set of [utils](https://supervision.roboflow.com/datasets/) that allow you to load, split, merge, and save datasets in one of the supported formats.
 
 ```python
 >>> import supervision as sv
 
 >>> dataset = sv.DetectionDataset.from_yolo(
-...     images_directory_path='...',
-...     annotations_directory_path='...',
-...     data_yaml_path='...'
+...     images_directory_path=...,
+...     annotations_directory_path=...,
+...     data_yaml_path=...
 ... )
 
 >>> dataset.classes
@@ -107,192 +126,133 @@ Read more about desktop, headless, and local installation in our [guide](https:/
 <details close>
 <summary>👉 more dataset utils</summary>
 
-- Load object detection/instance segmentation datasets in one of the supported formats
+- load
 
-    ```python
-    >>> dataset = sv.DetectionDataset.from_yolo(
-    ...     images_directory_path='...',
-    ...     annotations_directory_path='...',
-    ...     data_yaml_path='...'
-    ... )
+  ```python
+  >>> dataset = sv.DetectionDataset.from_yolo(
+  ...     images_directory_path=...,
+  ...     annotations_directory_path=...,
+  ...     data_yaml_path=...
+  ... )
 
-    >>> dataset = sv.DetectionDataset.from_pascal_voc(
-    ...     images_directory_path='...',
-    ...     annotations_directory_path='...'
-    ... )
+  >>> dataset = sv.DetectionDataset.from_pascal_voc(
+  ...     images_directory_path=...,
+  ...     annotations_directory_path=...
+  ... )
 
-    >>> dataset = sv.DetectionDataset.from_coco(
-    ...     images_directory_path='...',
-    ...     annotations_path='...'
-    ... )
-    ```
-  
-- Loop over dataset entries
+  >>> dataset = sv.DetectionDataset.from_coco(
+  ...     images_directory_path=...,
+  ...     annotations_path=...
+  ... )
+  ```
 
-    ```python
-    >>> for name, image, labels in dataset:
-    ...     print(labels.xyxy)
+- split
 
-    array([[404.      , 719.      , 538.      , 884.5     ],
-           [155.      , 497.      , 404.      , 833.5     ],
-           [ 20.154999, 347.825   , 416.125   , 915.895   ]], dtype=float32)
-    ```
-  
-- Split dataset for training, testing, and validation
-  
-    ```python
-    >>> train_dataset, test_dataset = dataset.split(split_ratio=0.7)
-    >>> test_dataset, valid_dataset = test_dataset.split(split_ratio=0.5)
-  
-    >>> len(train_dataset), len(test_dataset), len(valid_dataset)
-    (700, 150, 150)
-    ```
-  
-- Merge multiple datasets
+  ```python
+  >>> train_dataset, test_dataset = dataset.split(split_ratio=0.7)
+  >>> test_dataset, valid_dataset = test_dataset.split(split_ratio=0.5)
 
-    ```python
-    >>> ds_1 = sv.DetectionDataset(...)
-    >>> len(ds_1)
-    100
-    >>> ds_1.classes
-    ['dog', 'person']
-  
-    >>> ds_2 = sv.DetectionDataset(...)
-    >>> len(ds_2)
-    200
-    >>> ds_2.classes
-    ['cat']
-  
-    >>> ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
-    >>> len(ds_merged)
-    300
-    >>> ds_merged.classes
-    ['cat', 'dog', 'person']
-    ```
-  
-- Save object detection/instance segmentation datasets in one of the supported formats
-  
-    ```python
-    >>> dataset.as_yolo(
-    ...     images_directory_path='...',
-    ...     annotations_directory_path='...',
-    ...     data_yaml_path='...'
-    ... )
+  >>> len(train_dataset), len(test_dataset), len(valid_dataset)
+  (700, 150, 150)
+  ```
 
-    >>> dataset.as_pascal_voc(
-    ...     images_directory_path='...',
-    ...     annotations_directory_path='...'
-    ... )
+- merge
 
-    >>> dataset.as_coco(
-    ...     images_directory_path='...',
-    ...     annotations_path='...'
-    ... )
-    ```
-  
-- Convert labels between supported formats
-  
-    ```python
-    >>> sv.DetectionDataset.from_yolo(
-    ...     images_directory_path='...',
-    ...     annotations_directory_path='...',
-    ...     data_yaml_path='...'
-    ... ).as_pascal_voc(
-    ...     images_directory_path='...',
-    ...     annotations_directory_path='...'
-    ... )
-    ```
-  
-- Load classification datasets in one of the supported formats
+  ```python
+  >>> ds_1 = sv.DetectionDataset(...)
+  >>> len(ds_1)
+  100
+  >>> ds_1.classes
+  ['dog', 'person']
 
-    ```python
-    >>> cs = sv.ClassificationDataset.from_folder_structure(
-    ...     root_directory_path='...'
-    ... )
-    ```
+  >>> ds_2 = sv.DetectionDataset(...)
+  >>> len(ds_2)
+  200
+  >>> ds_2.classes
+  ['cat']
 
-- Save classification datasets in one of the supported formats
+  >>> ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
+  >>> len(ds_merged)
+  300
+  >>> ds_merged.classes
+  ['cat', 'dog', 'person']
+  ```
 
-    ```python
-    >>> cs.as_folder_structure(
-    ...     root_directory_path='...'
-    ... )
-    ```
+- save
 
-</details>
+  ```python
+  >>> dataset.as_yolo(
+  ...     images_directory_path=...,
+  ...     annotations_directory_path=...,
+  ...     data_yaml_path=...
+  ... )
 
-### [model evaluation](https://roboflow.github.io/supervision/metrics/detection/)
+  >>> dataset.as_pascal_voc(
+  ...     images_directory_path=...,
+  ...     annotations_directory_path=...
+  ... )
 
-```python
->>> import supervision as sv
+  >>> dataset.as_coco(
+  ...     images_directory_path=...,
+  ...     annotations_path=...
+  ... )
+  ```
 
->>> dataset = sv.DetectionDataset.from_yolo(...)
+- convert
 
->>> def callback(image: np.ndarray) -> sv.Detections:
-...     ...
+  ```python
+  >>> sv.DetectionDataset.from_yolo(
+  ...     images_directory_path=...,
+  ...     annotations_directory_path=...,
+  ...     data_yaml_path=...
+  ... ).as_pascal_voc(
+  ...     images_directory_path=...,
+  ...     annotations_directory_path=...
+  ... )
+  ```
 
->>> confusion_matrix = sv.ConfusionMatrix.benchmark(
-...     dataset = dataset,
-...     callback = callback
-... )
-
->>> confusion_matrix.matrix
-array([
-    [0., 0., 0., 0.],
-    [0., 1., 0., 1.],
-    [0., 1., 1., 0.],
-    [1., 1., 0., 0.]
-])
-```
-
-<details close>
-<summary>👉 more metrics</summary>
-
-- Mean average precision (mAP) for object detection tasks.
-
-    ```python
-    >>> import supervision as sv
-    
-    >>> dataset = sv.DetectionDataset.from_yolo(...)
-    
-    >>> def callback(image: np.ndarray) -> sv.Detections:
-    ...     ...
-    
-    >>> mean_average_precision = sv.MeanAveragePrecision.benchmark(
-    ...     dataset = dataset,
-    ...     callback = callback
-    ... )
-    
-    >>> mean_average_precision.map50_95
-    0.433 
-    ```
-  
 </details>
 
 ## 🎬 tutorials
 
 <p align="left">
-<a href="https://youtu.be/oEQYStnF2l8" title="Accelerate Image Annotation with SAM and Grounding DINO"><img src="https://github.com/SkalskiP/SkalskiP/assets/26109316/ae1ca38e-40b7-4b35-8582-e8ea5de3806e" alt="Accelerate Image Annotation with SAM and Grounding DINO" width="300px" align="left" /></a>
-<a href="https://youtu.be/oEQYStnF2l8" title="Accelerate Image Annotation with SAM and Grounding DINO"><strong>Accelerate Image Annotation with SAM and Grounding DINO</strong></a>
-<div><strong>Created: 20 Apr 2023</strong> | <strong>Updated: 20 Apr 2023</strong></div>
-<br/> Discover how to speed up your image annotation process using Grounding DINO and Segment Anything Model (SAM). Learn how to convert object detection datasets into instance segmentation datasets, and see the potential of using these models to automatically annotate your datasets for real-time detectors like YOLOv8... </p> 
+<a href="https://youtu.be/4Q3ut7vqD5o" title="Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking"><img src="https://github.com/roboflow/supervision/assets/26109316/54afdf1c-218c-4451-8f12-627fb85f1682" alt="Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking" width="300px" align="left" /></a>
+<a href="https://youtu.be/4Q3ut7vqD5o" title="Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking"><strong>Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking</strong></a>
+<div><strong>Created: 6 Sep 2023</strong> | <strong>Updated: 6 Sep 2023</strong></div>
+<br/> In this video, we explore real-time traffic analysis using YOLOv8 and ByteTrack to detect and track vehicles on aerial images. Harnessing the power of Python and Supervision, we delve deep into assigning cars to specific entry zones and understanding their direction of movement. By visualizing their paths, we gain insights into traffic flow across bustling roundabouts... </p>
 
-<br/> 
+<br/>
 
 <p align="left">
-<a href="https://youtu.be/oEQYStnF2l8" title="SAM - Segment Anything Model by Meta AI: Complete Guide"><img src="https://github.com/SkalskiP/SkalskiP/assets/26109316/6913ff11-53c6-4341-8d90-eaff3023c3fd" alt="SAM - Segment Anything Model by Meta AI: Complete Guide" width="300px" align="left" /></a>
-<a href="https://youtu.be/oEQYStnF2l8" title="SAM - Segment Anything Model by Meta AI: Complete Guide"><strong>SAM - Segment Anything Model by Meta AI: Complete Guide</strong></a>
+<a href="https://youtu.be/D-D6ZmadzPE" title="SAM - Segment Anything Model by Meta AI: Complete Guide"><img src="https://github.com/SkalskiP/SkalskiP/assets/26109316/6913ff11-53c6-4341-8d90-eaff3023c3fd" alt="SAM - Segment Anything Model by Meta AI: Complete Guide" width="300px" align="left" /></a>
+<a href="https://youtu.be/D-D6ZmadzPE" title="SAM - Segment Anything Model by Meta AI: Complete Guide"><strong>SAM - Segment Anything Model by Meta AI: Complete Guide</strong></a>
 <div><strong>Created: 11 Apr 2023</strong> | <strong>Updated: 11 Apr 2023</strong></div>
 <br/> Discover the incredible potential of Meta AI's Segment Anything Model (SAM)! We dive into SAM, an efficient and promptable model for image segmentation, which has revolutionized computer vision tasks. With over 1 billion masks on 11M licensed and privacy-respecting images, SAM's zero-shot performance is often competitive with or even superior to prior fully supervised results... </p>
 
+## 💜 built with supervision
+
+Did you build something cool using supervision? [Let us know!](https://github.com/roboflow/supervision/discussions/categories/built-with-supervision)
+
+https://user-images.githubusercontent.com/26109316/207858600-ee862b22-0353-440b-ad85-caa0c4777904.mp4
+
+https://github.com/roboflow/supervision/assets/26109316/c9436828-9fbf-4c25-ae8c-60e9c81b3900
+
+https://github.com/roboflow/supervision/assets/26109316/f84db7b5-79e2-4142-a1da-64daa43ce667
+
 ## 📚 documentation
 
-Visit our [documentation](https://roboflow.github.io/supervision) page to learn how supervision can help you build computer vision applications faster and more reliably. 
+Visit our [documentation](https://roboflow.github.io/supervision) page to learn how supervision can help you build computer vision applications faster and more reliably.
 
 ## 🏆 contribution
 
 We love your input! Please see our [contributing guide](https://github.com/roboflow/supervision/blob/main/CONTRIBUTING.md) to get started. Thank you 🙏 to all our contributors!
 
+<p align="center">
+    <a href="https://github.com/roboflow/supervision/graphs/contributors">
+      <img src="https://contrib.rocks/image?repo=roboflow/supervision" />
+    </a>
+</p>
+
 <br>
 
 <div align="center">
@@ -340,5 +300,4 @@ We love your input! Please see our [contributing guide](https://github.com/robof
       </a>
       </a>
   </div>
-
 </div>

docs/CNAME

@@ -0,0 +1 @@
+supervision.roboflow.com

docs/annotators.md

@@ -0,0 +1,396 @@
+=== "BoundingBox"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> bounding_box_annotator = sv.BoundingBoxAnnotator()
+    >>> annotated_frame = bounding_box_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![bounding-box-annotator-example](https://media.roboflow.com/supervision-annotator-examples/bounding-box-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "BoxCorner"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> corner_annotator = sv.BoxCornerAnnotator()
+    >>> annotated_frame = corner_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![box-corner-annotator-example](https://media.roboflow.com/supervision-annotator-examples/box-corner-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Color"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> color_annotator = sv.ColorAnnotator()
+    >>> annotated_frame = color_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![box-mask-annotator-example](https://media.roboflow.com/supervision-annotator-examples/box-mask-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Circle"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> circle_annotator = sv.CircleAnnotator()
+    >>> annotated_frame = circle_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![circle-annotator-example](https://media.roboflow.com/supervision-annotator-examples/circle-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Dot"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> dot_annotator = sv.DotAnnotator()
+    >>> annotated_frame = dot_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![circle-annotator-example](https://media.roboflow.com/supervision-annotator-examples/dot-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Triangle"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> triangle_annotator = sv.TriangleAnnotator()
+    >>> annotated_frame = triangle_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![triangle-annotator-example](https://media.roboflow.com/supervision-annotator-examples/triangle-annotator-example.png){ align=center width="800" }
+
+    </div>
+
+=== "Ellipse"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> ellipse_annotator = sv.EllipseAnnotator()
+    >>> annotated_frame = ellipse_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![ellipse-annotator-example](https://media.roboflow.com/supervision-annotator-examples/ellipse-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Halo"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> halo_annotator = sv.HaloAnnotator()
+    >>> annotated_frame = halo_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![ellipse-annotator-example](https://media.roboflow.com/supervision-annotator-examples/halo-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Mask"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> mask_annotator = sv.MaskAnnotator()
+    >>> annotated_frame = mask_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![mask-annotator-example](https://media.roboflow.com/supervision-annotator-examples/mask-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Polygon"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> polygon_annotator = sv.PolygonAnnotator()
+    >>> annotated_frame = polygon_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![polygon-annotator-example](https://media.roboflow.com/supervision-annotator-examples/polygon-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Label"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+    >>> annotated_frame = label_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![label-annotator-example](https://media.roboflow.com/supervision-annotator-examples/label-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Blur"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> blur_annotator = sv.BlurAnnotator()
+    >>> annotated_frame = blur_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![blur-annotator-example](https://media.roboflow.com/supervision-annotator-examples/blur-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "Pixelate"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> pixelate_annotator = sv.PixelateAnnotator()
+    >>> annotated_frame = pixelate_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![pixelate-annotator-example](https://media.roboflow.com/supervision-annotator-examples/pixelate-annotator-example-10.png){ align=center width="800" }
+
+    </div>
+
+=== "Trace"
+
+    ```python
+    >>> import supervision as sv
+    >>> from ultralytics import YOLO
+
+    >>> model = YOLO('yolov8x.pt')
+
+    >>> trace_annotator = sv.TraceAnnotator()
+
+    >>> video_info = sv.VideoInfo.from_video_path(video_path='...')
+    >>> frames_generator = get_video_frames_generator(source_path='...')
+    >>> tracker = sv.ByteTrack()
+
+    >>> with sv.VideoSink(target_path='...', video_info=video_info) as sink:
+    ...    for frame in frames_generator:
+    ...        result = model(frame)[0]
+    ...        detections = sv.Detections.from_ultralytics(result)
+    ...        detections = tracker.update_with_detections(detections)
+    ...        annotated_frame = trace_annotator.annotate(
+    ...            scene=frame.copy(),
+    ...            detections=detections)
+    ...        sink.write_frame(frame=annotated_frame)
+    ```
+
+    <div class="result" markdown>
+
+    ![trace-annotator-example](https://media.roboflow.com/supervision-annotator-examples/trace-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "HeatMap"
+
+    ```python
+    >>> import supervision as sv
+    >>> from ultralytics import YOLO
+
+    >>> model = YOLO('yolov8x.pt')
+
+    >>> heat_map_annotator = sv.HeatMapAnnotator()
+
+    >>> video_info = sv.VideoInfo.from_video_path(video_path='...')
+    >>> frames_generator = get_video_frames_generator(source_path='...')
+
+    >>> with sv.VideoSink(target_path='...', video_info=video_info) as sink:
+    ...    for frame in frames_generator:
+    ...        result = model(frame)[0]
+    ...        detections = sv.Detections.from_ultralytics(result)
+    ...        annotated_frame = heat_map_annotator.annotate(
+    ...            scene=frame.copy(),
+    ...            detections=detections)
+    ...        sink.write_frame(frame=annotated_frame)
+    ```
+
+    <div class="result" markdown>
+
+    ![trace-annotator-example](https://media.roboflow.com/supervision-annotator-examples/heat-map-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+## BoundingBoxAnnotator
+
+:::supervision.annotators.core.BoundingBoxAnnotator
+
+## BoxCornerAnnotator
+
+:::supervision.annotators.core.BoxCornerAnnotator
+
+## ColorAnnotator
+
+:::supervision.annotators.core.ColorAnnotator
+
+## CircleAnnotator
+
+:::supervision.annotators.core.CircleAnnotator
+
+## DotAnnotator
+
+:::supervision.annotators.core.DotAnnotator
+
+## TriangleAnnotator
+
+:::supervision.annotators.core.TriangleAnnotator
+
+## EllipseAnnotator
+
+:::supervision.annotators.core.EllipseAnnotator
+
+## HaloAnnotator
+
+:::supervision.annotators.core.HaloAnnotator
+
+## HeatMapAnnotator
+
+:::supervision.annotators.core.HeatMapAnnotator
+
+## MaskAnnotator
+
+:::supervision.annotators.core.MaskAnnotator
+
+## PolygonAnnotator
+
+:::supervision.annotators.core.PolygonAnnotator
+
+## LabelAnnotator
+
+:::supervision.annotators.core.LabelAnnotator
+
+## BlurAnnotator
+
+:::supervision.annotators.core.BlurAnnotator
+
+## PixelateAnnotator
+
+:::supervision.annotators.core.PixelateAnnotator
+
+## TraceAnnotator
+
+:::supervision.annotators.core.TraceAnnotator
+
+## ColorLookup
+
+:::supervision.annotators.utils.ColorLookup

docs/assets.md

@@ -0,0 +1,21 @@
+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]
+    ```
+
+## download_assets
+
+:::supervision.assets.downloader.download_assets
+
+## VideoAssets
+
+:::supervision.assets.list.VideoAssets

docs/changelog.md

@@ -1,6 +1,177 @@
+### 0.17.0 <small>December 06, 2023</small>
+
+- Added [#633](https://github.com/roboflow/supervision/pull/633): [`sv.PixelateAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.PixelateAnnotator) allowing to pixelate objects on images and videos.
+
+- Added [#652](https://github.com/roboflow/supervision/pull/652): [`sv.TriangleAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.TriangleAnnotator) allowing to annotate images and videos with triangle markers.
+
+- Added [#602](https://github.com/roboflow/supervision/pull/602): [`sv.PolygonAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.PolygonAnnotator) allowing to annotate images and videos with segmentation mask outline.
+
+```python
+>>> import supervision as sv
+
+>>> image = ...
+>>> detections = sv.Detections(...)
+
+>>> polygon_annotator = sv.PolygonAnnotator()
+>>> annotated_frame = polygon_annotator.annotate(
+...     scene=image.copy(),
+...     detections=detections
+... )
+```
+
+- Added [#476](https://github.com/roboflow/supervision/pull/476): [`sv.assets`](https://supervision.roboflow.com/assets/) allowing download of video files that you can use in your demos.
+
+```python
+>>> from supervision.assets import download_assets, VideoAssets
+>>> download_assets(VideoAssets.VEHICLES)
+"vehicles.mp4"
+```
+
+- Added [#605](https://github.com/roboflow/supervision/pull/605): [`Position.CENTER_OF_MASS`](https://supervision.roboflow.com/geometry/core/#position) allowing to place labels in center of mass of segmentation masks.
+
+- Added [#651](https://github.com/roboflow/supervision/pull/651): [`sv.scale_boxes`](https://supervision.roboflow.com/detection/utils/#supervision.detection.utils.scale_boxes) allowing to scale [`sv.Detections.xyxy`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections) values.
+
+- Added [#637](https://github.com/roboflow/supervision/pull/637): [`sv.calculate_dynamic_text_scale`](https://supervision.roboflow.com/draw/utils/#supervision.draw.utils.calculate_dynamic_text_scale) and [`sv.calculate_dynamic_line_thickness`](https://supervision.roboflow.com/draw/utils/#supervision.draw.utils.calculate_dynamic_line_thickness) allowing text scale and line thickness to match image resolution.
+
+- Added [#620](https://github.com/roboflow/supervision/pull/620): [`sv.Color.as_hex`](https://supervision.roboflow.com/draw/color/#supervision.draw.color.Color.as_hex) allowing to extract color value in HEX format.
+
+- Added [#572](https://github.com/roboflow/supervision/pull/572): [`sv.Classifications.from_timm`](https://supervision.roboflow.com/classification/core/#supervision.classification.core.Classifications.from_timm) allowing to load classification result from [timm](https://huggingface.co/docs/hub/timm) models.
+
+- Added [#478](https://github.com/roboflow/supervision/pull/478): [`sv.Classifications.from_clip`](https://supervision.roboflow.com/classification/core/#supervision.classification.core.Classifications.from_clip) allowing to load classification result from [clip](https://github.com/openai/clip) model.
+
+- Added [#571](https://github.com/roboflow/supervision/pull/571): [`sv.Detections.from_azure_analyze_image`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_azure_analyze_image) allowing to load detection results from [Azure Image Analysis](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/concept-object-detection-40).
+
+- Changed [#646](https://github.com/roboflow/supervision/pull/646): `sv.BoxMaskAnnotator` renaming it to [`sv.ColorAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.ColorAnnotator).
+
+- Changed [#606](https://github.com/roboflow/supervision/pull/606): [`sv.MaskAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.MaskAnnotator) to make it **5x faster**.
+
+- Fixed [#584](https://github.com/roboflow/supervision/pull/584): [`sv.DetectionDataset.from_yolo`](https://supervision.roboflow.com/datasets/#supervision.dataset.core.DetectionDataset.from_yolo) to ignore empty lines in annotation files.
+
+- Fixed [#555](https://github.com/roboflow/supervision/pull/555): [`sv.BlurAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.BlurAnnotator) to trim negative coordinates before bluring detections.
+
+- Fixed [#511](https://github.com/roboflow/supervision/pull/511): [`sv.TraceAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.TraceAnnotator) to respect trace position.
+
+### 0.16.0 <small>October 19, 2023</small>
+
+- Added [#422](https://github.com/roboflow/supervision/pull/422): [`sv.BoxMaskAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.BoxMaskAnnotator) allowing to annotate images and videos with mox masks.
+
+- Added [#433](https://github.com/roboflow/supervision/pull/433): [`sv.HaloAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.HaloAnnotator) allowing to annotate images and videos with halo effect.
+
+```python
+>>> import supervision as sv
+
+>>> image = ...
+>>> detections = sv.Detections(...)
+
+>>> halo_annotator = sv.HaloAnnotator()
+>>> annotated_frame = halo_annotator.annotate(
+...     scene=image.copy(),
+...     detections=detections
+... )
+```
+
+- Added [#466](https://github.com/roboflow/supervision/pull/466): [`sv.HeatMapAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.HeatMapAnnotator) allowing to annotate videos with heat maps.
+
+- Added [#492](https://github.com/roboflow/supervision/pull/492): [`sv.DotAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.DotAnnotator) allowing to annotate images and videos with dots.
+
+- Added [#449](https://github.com/roboflow/supervision/pull/449): [`sv.draw_image`](https://supervision.roboflow.com/draw/utils/#supervision.draw.utils.draw_image) allowing to draw an image onto a given scene with specified opacity and dimensions.
+
+- Added [#280](https://github.com/roboflow/supervision/pull/280): [`sv.FPSMonitor`](https://supervision.roboflow.com/utils/video/#supervision.utils.video.FPSMonitor) for monitoring frames per second (FPS) to benchmark latency.
+
+- Added [#454](https://github.com/roboflow/supervision/pull/454): 🤗 Hugging Face Annotators [space](https://huggingface.co/spaces/Roboflow/Annotators).
+
+- Changed [#482](https://github.com/roboflow/supervision/pull/482): [`sv.LineZone.tigger`](https://supervision.roboflow.com/detection/tools/line_zone/#supervision.detection.line_counter.LineZone.trigger) now return `Tuple[np.ndarray, np.ndarray]`. The first array indicates which detections have crossed the line from outside to inside. The second array indicates which detections have crossed the line from inside to outside.
+
+- Changed [#465](https://github.com/roboflow/supervision/pull/465): Annotator argument name from `color_map: str` to `color_lookup: ColorLookup` enum to increase type safety.
+
+- Changed [#426](https://github.com/roboflow/supervision/pull/426): [`sv.MaskAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.MaskAnnotator) allowing 2x faster annotation.
+
+- Fixed [#477](https://github.com/roboflow/supervision/pull/477): Poetry env definition allowing proper local installation.
+
+- Fixed [#430](https://github.com/roboflow/supervision/pull/430):  [`sv.ByteTrack`](https://supervision.roboflow.com/trackers/#supervision.tracker.byte_tracker.core.ByteTrack) to return `np.array([], dtype=int)` when `svDetections` is empty.
+
+!!! warning
+
+    `sv.Detections.from_yolov8` and `sv.Classifications.from_yolov8` as those are now replaced by [`sv.Detections.from_ultralytics`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_ultralytics) and [`sv.Classifications.from_ultralytics`](https://supervision.roboflow.com/classification/core/#supervision.classification.core.Classifications.from_ultralytics).
+
+
+### 0.15.0 <small>October 5, 2023</small>
+
+- Added [#170](https://github.com/roboflow/supervision/pull/170): [`sv.BoundingBoxAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.BoundingBoxAnnotator) allowing to annotate images and videos with bounding boxes.
+
+- Added [#170](https://github.com/roboflow/supervision/pull/170): [`sv.BoxCornerAnnotator `](https://supervision.roboflow.com/annotators/#supervision.annotators.core.BoxCornerAnnotator) allowing to annotate images and videos with just bounding box corners.
+
+- Added [#170](https://github.com/roboflow/supervision/pull/170): [`sv.MaskAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.MaskAnnotator) allowing to annotate images and videos with segmentation masks.
+
+- Added [#170](https://github.com/roboflow/supervision/pull/170): [`sv.EllipseAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.EllipseAnnotator) allowing to annotate images and videos with ellipses (sports game style).
+
+- Added [#386](https://github.com/roboflow/supervision/pull/386): [`sv.CircleAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.CircleAnnotator) allowing to annotate images and videos with circles.
+
+- Added [#354](https://github.com/roboflow/supervision/pull/354): [`sv.TraceAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.TraceAnnotator) allowing to draw path of moving objects on videos.
+
+- Added [#405](https://github.com/roboflow/supervision/pull/405): [`sv.BlurAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.BlurAnnotator) allowing to blur objects on images and videos.
+
+```python
+>>> import supervision as sv
+
+>>> image = ...
+>>> detections = sv.Detections(...)
+
+>>> bounding_box_annotator = sv.BoundingBoxAnnotator()
+>>> annotated_frame = bounding_box_annotator.annotate(
+...     scene=image.copy(),
+...     detections=detections
+... )
+```
+
+- Added [#354](https://github.com/roboflow/supervision/pull/354): Supervision usage [example](https://github.com/roboflow/supervision/tree/develop/examples/traffic_analysis). You can now learn how to perform traffic flow analysis with Supervision.
+
+- Changed [#399](https://github.com/roboflow/supervision/pull/399): [`sv.Detections.from_roboflow`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_roboflow) now does not require `class_list` to be specified. The `class_id` value can be extracted directly from the [inference](https://github.com/roboflow/inference) response.
+
+- Changed [#381](https://github.com/roboflow/supervision/pull/381): [`sv.VideoSink`](https://supervision.roboflow.com/utils/video/#videosink) now allows to customize the output codec.
+
+- Changed [#361](https://github.com/roboflow/supervision/pull/361): [`sv.InferenceSlicer`](https://supervision.roboflow.com/detection/tools/inference_slicer/#supervision.detection.tools.inference_slicer.InferenceSlicer) can now operate in multithreading mode.
+
+- Fixed [#348](https://github.com/roboflow/supervision/pull/348): [`sv.Detections.from_deepsparse`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_deepsparse) to allow processing empty [deepsparse](https://github.com/neuralmagic/deepsparse) result object.
+
+### 0.14.0 <small>August 31, 2023</small>
+
+- Added [#282](https://github.com/roboflow/supervision/pull/282): support for SAHI inference technique with [`sv.InferenceSlicer`](https://supervision.roboflow.com/detection/tools/inference_slicer).
+
+```python
+>>> import cv2
+>>> import supervision as sv
+>>> from ultralytics import YOLO
+
+>>> image = cv2.imread(SOURCE_IMAGE_PATH)
+>>> model = YOLO(...)
+
+>>> def callback(image_slice: np.ndarray) -> sv.Detections:
+...     result = model(image_slice)[0]
+...     return sv.Detections.from_ultralytics(result)
+
+>>> slicer = sv.InferenceSlicer(callback = callback)
+
+>>> detections = slicer(image)
+```
+
+- Added [#297](https://github.com/roboflow/supervision/pull/297): [`Detections.from_deepsparse`](https://roboflow.github.io/supervision/detection/core/#supervision.detection.core.Detections.from_deepsparse) to enable seamless integration with [DeepSparse](https://github.com/neuralmagic/deepsparse) framework.
+
+- Added [#281](https://github.com/roboflow/supervision/pull/281): [`sv.Classifications.from_ultralytics`](https://supervision.roboflow.com/classification/core/#supervision.classification.core.Classifications.from_ultralytics) to enable seamless integration with [Ultralytics](https://github.com/ultralytics/ultralytics) framework. This will enable you to use supervision with all [models](https://docs.ultralytics.com/models/) that Ultralytics supports.
+
+!!! warning
+
+    [sv.Detections.from_yolov8](https://roboflow.github.io/supervision/detection/core/#supervision.detection.core.Detections.from_yolov8) and [sv.Classifications.from_yolov8](https://supervision.roboflow.com/classification/core/#supervision.classification.core.Classifications.from_yolov8) are now deprecated and will be removed with supervision-0.16.0 release.
+
+- Added [#341](https://github.com/roboflow/supervision/pull/341): First supervision usage example script showing how to detect and track objects on video using YOLOv8 + Supervision.
+
+- Changed [#296](https://github.com/roboflow/supervision/pull/296): [`sv.ClassificationDataset`](https://supervision.roboflow.com/dataset/core/#supervision.dataset.core.ClassificationDataset) and [`sv.DetectionDataset`](https://supervision.roboflow.com/dataset/core/#supervision.dataset.core.DetectionDataset) now use image path (not image name) as dataset keys.
+
+- Fixed [#300](https://github.com/roboflow/supervision/pull/300): [`Detections.from_roboflow`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_roboflow) to filter out polygons with less than 3 points.
+
 ### 0.13.0 <small>August 8, 2023</small>
 
-- Added [#236](https://github.com/roboflow/supervision/pull/236): support for mean average precision (mAP) for object detection models with [`sv.MeanAveragePrecision`](https://roboflow.github.io/supervision/metrics/detection/#meanaverageprecision). 
+- Added [#236](https://github.com/roboflow/supervision/pull/236): support for mean average precision (mAP) for object detection models with [`sv.MeanAveragePrecision`](https://roboflow.github.io/supervision/metrics/detection/#meanaverageprecision).
 
 ```python
 >>> import supervision as sv
@@ -83,7 +254,7 @@ array([
 
 ### 0.11.0 <small>June 28, 2023</small>
 
-- Added [#150](https://github.com/roboflow/supervision/pull/150): ability to load and save [`sv.DetectionDataset`](https://roboflow.github.io/supervision/dataset/core/#detectiondataset) in COCO format using [`as_coco`](https://roboflow.github.io/supervision/dataset/core/#supervision.dataset.core.DetectionDataset.as_coco) and [`from_coco`](https://roboflow.github.io/supervision/dataset/core/#supervision.dataset.core.DetectionDataset.from_coco) methods. 
+- Added [#150](https://github.com/roboflow/supervision/pull/150): ability to load and save [`sv.DetectionDataset`](https://roboflow.github.io/supervision/dataset/core/#detectiondataset) in COCO format using [`as_coco`](https://roboflow.github.io/supervision/dataset/core/#supervision.dataset.core.DetectionDataset.as_coco) and [`from_coco`](https://roboflow.github.io/supervision/dataset/core/#supervision.dataset.core.DetectionDataset.from_coco) methods.
 
 ```python
 >>> import supervision as sv
@@ -99,7 +270,7 @@ array([
 ... )
 ```
 
-- Added [#158](https://github.com/roboflow/supervision/pull/158): ability to marge multiple [`sv.DetectionDataset`](https://roboflow.github.io/supervision/dataset/core/#detectiondataset) together using [`merge`](https://roboflow.github.io/supervision/dataset/core/#supervision.dataset.core.DetectionDataset.merge) method. 
+- Added [#158](https://github.com/roboflow/supervision/pull/158): ability to marge multiple [`sv.DetectionDataset`](https://roboflow.github.io/supervision/dataset/core/#detectiondataset) together using [`merge`](https://roboflow.github.io/supervision/dataset/core/#supervision.dataset.core.DetectionDataset.merge) method.
 
 ```python
 >>> import supervision as sv
@@ -145,11 +316,11 @@ array([
 
 - Added [#125](https://github.com/roboflow/supervision/pull/125): support for [`sv.ClassificationDataset.split`](https://roboflow.github.io/supervision/dataset/core/#supervision.dataset.core.ClassificationDataset.split) allowing to divide `sv.ClassificationDataset` into two parts.
 
-- Added [#110](https://github.com/roboflow/supervision/pull/110): ability to extract masks from Roboflow API results using [`sv.Detections.from_roboflow`](https://roboflow.github.io/supervision/detection/core/#supervision.detection.core.Detections.from_roboflow). 
+- Added [#110](https://github.com/roboflow/supervision/pull/110): ability to extract masks from Roboflow API results using [`sv.Detections.from_roboflow`](https://roboflow.github.io/supervision/detection/core/#supervision.detection.core.Detections.from_roboflow).
 
 - Added [commit hash](https://github.com/roboflow/supervision/commit/d000292eb2f2342544e0947b65528082e60fb8d6): Supervision Quickstart [notebook](https://colab.research.google.com/github/roboflow/supervision/blob/main/demo.ipynb) where you can learn more about Detection, Dataset and Video APIs.
 
-- Changed [#135](https://github.com/roboflow/supervision/pull/135): `sv.get_video_frames_generator` documentation to better describe actual behavior.  
+- Changed [#135](https://github.com/roboflow/supervision/pull/135): `sv.get_video_frames_generator` documentation to better describe actual behavior.
 
 ### 0.9.0 <small>June 7, 2023</small>
 
@@ -168,7 +339,7 @@ array([
 ```
 
 - Added [#101](https://github.com/roboflow/supervision/pull/101): ability to extract masks from YOLOv8 result using [`sv.Detections.from_yolov8`](https://roboflow.github.io/supervision/detection/core/#supervision.detection.core.Detections.from_yolov8). Here is an example illustrating how to extract boolean masks from the result of the YOLOv8 model inference.
- 
+
 - Added [#122](https://github.com/roboflow/supervision/pull/122): ability to crop image using [`sv.crop`](https://roboflow.github.io/supervision/utils/image/#crop). Here is an example showing how to get a separate crop for each detection in `sv.Detections`.
 
 - Added [#120](https://github.com/roboflow/supervision/pull/120): ability to conveniently save multiple images into directory using [`sv.ImageSink`](https://roboflow.github.io/supervision/utils/image/#imagesink). Here is an example showing how to save every tenth video frame as a separate image.
@@ -186,7 +357,7 @@ array([
 ### 0.8.0 <small>May 17, 2023</small>
 
 - Added [#100](https://github.com/roboflow/supervision/pull/100): support for dataset inheritance. The current `Dataset` got renamed to `DetectionDataset`. Now [`DetectionDataset`](https://roboflow.github.io/supervision/dataset/core/#detectiondataset) inherits from `BaseDataset`. This change was made to enforce the future consistency of APIs of different types of computer vision datasets.
-- Added [#100](https://github.com/roboflow/supervision/pull/100): ability to save datasets in YOLO format using [`DetectionDataset.as_yolo`](https://roboflow.github.io/supervision/dataset/core/#supervision.dataset.core.DetectionDataset.as_yolo). 
+- Added [#100](https://github.com/roboflow/supervision/pull/100): ability to save datasets in YOLO format using [`DetectionDataset.as_yolo`](https://roboflow.github.io/supervision/dataset/core/#supervision.dataset.core.DetectionDataset.as_yolo).
 
 ```python
 >>> import roboflow
@@ -210,7 +381,7 @@ array([
 ['dog', 'person']
 ```
 
-- Added [#102](https://github.com/roboflow/supervision/pull/103): support for [`DetectionDataset.split`](https://roboflow.github.io/supervision/dataset/core/#supervision.dataset.core.DetectionDataset.split) allowing to divide `DetectionDataset` into two parts. 
+- Added [#102](https://github.com/roboflow/supervision/pull/103): support for [`DetectionDataset.split`](https://roboflow.github.io/supervision/dataset/core/#supervision.dataset.core.DetectionDataset.split) allowing to divide `DetectionDataset` into two parts.
 
 ```python
 >>> import supervision as sv
@@ -227,14 +398,14 @@ array([
 ### 0.7.0 <small>May 11, 2023</small>
 
 - Added [#91](https://github.com/roboflow/supervision/pull/91): `Detections.from_yolo_nas` to enable seamless integration with [YOLO-NAS](https://github.com/Deci-AI/super-gradients/blob/master/YOLONAS.md) model.
-- Added [#86](https://github.com/roboflow/supervision/pull/86): ability to load datasets in YOLO format using `Dataset.from_yolo`. 
+- Added [#86](https://github.com/roboflow/supervision/pull/86): ability to load datasets in YOLO format using `Dataset.from_yolo`.
 - Added [#84](https://github.com/roboflow/supervision/pull/84): `Detections.merge` to merge multiple `Detections` objects together.
 - Fixed [#81](https://github.com/roboflow/supervision/pull/81): `LineZoneAnnotator.annotate` does not return annotated frame.
 - Changed [#44](https://github.com/roboflow/supervision/pull/44): `LineZoneAnnotator.annotate` to allow for custom text for the in and out tags.
 
 ### 0.6.0 <small>April 19, 2023</small>
 
-- Added [#71](https://github.com/roboflow/supervision/pull/71): initial `Dataset` support and ability to save `Detections` in Pascal VOC XML format. 
+- Added [#71](https://github.com/roboflow/supervision/pull/71): initial `Dataset` support and ability to save `Detections` in Pascal VOC XML format.
 - Added [#71](https://github.com/roboflow/supervision/pull/71): new `mask_to_polygons`, `filter_polygons_by_area`, `polygon_to_xyxy` and `approximate_polygon` utilities.
 - Added [#72](https://github.com/roboflow/supervision/pull/72): ability to load Pascal VOC XML **object detections** dataset as `Dataset`.
 - Changed [#70](https://github.com/roboflow/supervision/pull/70): order of `Detections` attributes to make it consistent with order of objects in `__iter__` tuple.
@@ -256,7 +427,7 @@ array([
 - Added [#58](https://github.com/roboflow/supervision/pull/58): `Detections.from_sam` to enable native Segment Anything Model (SAM) support.
 - Changed [#58](https://github.com/roboflow/supervision/pull/58): `Detections.area` behaviour to work not only with boxes but also with masks.
 
-### 0.4.0 <small>April 5, 2023</small> 
+### 0.4.0 <small>April 5, 2023</small>
 
 - Added [#46](https://github.com/roboflow/supervision/discussions/48): `Detections.empty` to allow easy creation of empty `Detections` objects.
 - Added [#56](https://github.com/roboflow/supervision/pull/56): `Detections.from_roboflow` to allow easy creation of `Detections` objects from Roboflow API inference results.
@@ -264,28 +435,28 @@ array([
 - Added [#56](https://github.com/roboflow/supervision/pull/56): initial support for Pascal VOC XML format with `detections_to_voc_xml` method.
 - Changed [#56](https://github.com/roboflow/supervision/pull/56): `show_frame_in_notebook` refactored and renamed to `plot_image`.
 
-### 0.3.2 <small>March 23, 2023</small> 
+### 0.3.2 <small>March 23, 2023</small>
 
-- Changed [#50](https://github.com/roboflow/supervision/issues/50): Allow `Detections.class_id` to be `None`. 
+- Changed [#50](https://github.com/roboflow/supervision/issues/50): Allow `Detections.class_id` to be `None`.
 
-### 0.3.1 <small>March 6, 2023</small> 
+### 0.3.1 <small>March 6, 2023</small>
 
 - Fixed [#41](https://github.com/roboflow/supervision/issues/41): `PolygonZone` throws an exception when the object touches the bottom edge of the image.
 - Fixed [#42](https://github.com/roboflow/supervision/issues/42): `Detections.wth_nms` method throws an exception when `Detections` is empty.
 - Changed [#36](https://github.com/roboflow/supervision/pull/36): `Detections.wth_nms` support class agnostic and non-class agnostic case.
 
-### 0.3.0 <small>March 6, 2023</small> 
+### 0.3.0 <small>March 6, 2023</small>
 
 - Changed: Allow `Detections.confidence` to be `None`.
-- Added: `Detections.from_transformers` and `Detections.from_detectron2` to enable seamless integration with Transformers and Detectron2 models. 
+- Added: `Detections.from_transformers` and `Detections.from_detectron2` to enable seamless integration with Transformers and Detectron2 models.
 - Added: `Detections.area` to dynamically calculate bounding box area.
-- Added: `Detections.wth_nms` to filter out double detections with NMS. Initial - only class agnostic - implementation. 
+- Added: `Detections.wth_nms` to filter out double detections with NMS. Initial - only class agnostic - implementation.
 
-### 0.2.0 <small>February 2, 2023</small> 
+### 0.2.0 <small>February 2, 2023</small>
 
 - Added: Advanced `Detections` filtering with pandas-like API.
 - Added: `Detections.from_yolov5` and `Detections.from_yolov8` to enable seamless integration with YOLOv5 and YOLOv8 models.
 
-### 0.1.0 <small>January 19, 2023</small> 
+### 0.1.0 <small>January 19, 2023</small>
 
 Say hello to Supervision 👋

docs/datasets.md

@@ -1,6 +1,6 @@
 !!! warning
 
-    Dataset API is still fluid and may change. If you use Dataset API in your project until further notice, freeze the 
+    Dataset API is still fluid and may change. If you use Dataset API in your project until further notice, freeze the
     `supervision` version in your `requirements.txt` or `setup.py`.
 
 ## DetectionDataset
@@ -9,4 +9,4 @@
 
 ## ClassificationDataset
 
-:::supervision.dataset.core.ClassificationDataset
+:::supervision.dataset.core.ClassificationDataset

docs/detection/annotate.md

@@ -1,7 +0,0 @@
-## BoxAnnotator
-
-:::supervision.detection.annotate.BoxAnnotator
-
-## MaskAnnotator
-
-:::supervision.detection.annotate.MaskAnnotator

docs/detection/tools/inference_slicer.md

@@ -0,0 +1,3 @@
+## InferenceSlicer
+
+:::supervision.detection.tools.inference_slicer.InferenceSlicer

docs/detection/tools/line_zone.md

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

docs/detection/tools/polygon_zone.md

@@ -4,4 +4,4 @@
 
 ## PolygonZoneAnnotator
 
-:::supervision.detection.tools.polygon_zone.PolygonZoneAnnotator
+:::supervision.detection.tools.polygon_zone.PolygonZoneAnnotator

docs/detection/utils.md

@@ -24,4 +24,12 @@
 
 ## filter_polygons_by_area
 
-:::supervision.detection.utils.filter_polygons_by_area
+:::supervision.detection.utils.filter_polygons_by_area
+
+## move_boxes
+
+:::supervision.detection.utils.move_boxes
+
+## scale_boxes
+
+:::supervision.detection.utils.scale_boxes

docs/draw/color.md

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

docs/draw/utils.md

@@ -16,4 +16,16 @@
 
 ## draw_text
 
-:::supervision.draw.utils.draw_text
+:::supervision.draw.utils.draw_text
+
+## draw_image
+
+:::supervision.draw.utils.draw_image
+
+## calculate_dynamic_font_scale
+
+:::supervision.draw.utils.calculate_dynamic_text_scale
+
+## calculate_dynamic_line_thickness
+
+:::supervision.draw.utils.calculate_dynamic_line_thickness

docs/geometry/core.md

@@ -0,0 +1,3 @@
+## Position
+
+:::supervision.geometry.core.Position

docs/how_to/detect_and_annotate.md

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

docs/how_to/evaluate_model.md

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

docs/how_to/filter_detections.md

@@ -1,10 +1,7 @@
-## advanced filtering
-
-
-The advanced filtering capabilities of the `Detections` class offer users a versatile and efficient way to narrow down 
-and refine object detections. This section outlines various filtering methods, including filtering by specific class 
-or a set of classes, confidence, object area, bounding box area, relative area, box dimensions, and designated zones. 
-Each method is demonstrated with concise code examples to provide users with a clear understanding of how to implement 
+The advanced filtering capabilities of the `Detections` class offer users a versatile and efficient way to narrow down
+and refine object detections. This section outlines various filtering methods, including filtering by specific class
+or a set of classes, confidence, object area, bounding box area, relative area, box dimensions, and designated zones.
+Each method is demonstrated with concise code examples to provide users with a clear understanding of how to implement
 the filters in their applications.
 
 ### by specific class
@@ -44,14 +41,14 @@ Allows you to select detections that belong only to one selected class.
 
 ### by set of classes
 
-Allows you to select detections that belong only to selected set of classes. 
+Allows you to select detections that belong only to selected set of classes.
 
 === "After"
 
     ```python
     import numpy as np
     import supervision as sv
-    
+
     selected_classes = [0, 2, 3]
     detections = sv.Detections(...)
     detections = detections[np.isin(detections.class_id, selected_classes)]
@@ -68,7 +65,7 @@ Allows you to select detections that belong only to selected set of classes.
     ```python
     import numpy as np
     import supervision as sv
-    
+
     class_id = [0, 2, 3]
     detections = sv.Detections(...)
     detections = detections[np.isin(detections.class_id, class_id)]
@@ -116,8 +113,8 @@ Allows you to select detections with specific confidence value, for example high
 
 ### by area
 
-Allows you to select detections based on their size. We define the area as the number of pixels occupied by the 
-detection in the image. In the example below, we have sifted out the detections that are too small. 
+Allows you to select detections based on their size. We define the area as the number of pixels occupied by the
+detection in the image. In the example below, we have sifted out the detections that are too small.
 
 === "After"
 
@@ -151,9 +148,9 @@ detection in the image. In the example below, we have sifted out the detections
 
 ### by relative area
 
-Allows you to select detections based on their size in relation to the size of whole image. Sometimes the concept of 
-detection size changes depending on the image. Detection occupying 10000 square px can be large on a 1280x720 image 
-but small on a 3840x2160 image. In such cases, we can filter out detections based on the percentage of the image area 
+Allows you to select detections based on their size in relation to the size of whole image. Sometimes the concept of
+detection size changes depending on the image. Detection occupying 10000 square px can be large on a 1280x720 image
+but small on a 3840x2160 image. In such cases, we can filter out detections based on the percentage of the image area
 occupied by them. In the example below, we remove too large detections.
 
 === "After"
@@ -164,7 +161,7 @@ occupied by them. In the example below, we remove too large detections.
     image = ...
     height, width, channels = image.shape
     image_area = height * width
-    
+
     detections = sv.Detections(...)
     detections = detections[(detections.area / image_area) < 0.8]
     ```
@@ -183,7 +180,7 @@ occupied by them. In the example below, we remove too large detections.
     image = ...
     height, width, channels = image.shape
     image_area = height * width
-    
+
     detections = sv.Detections(...)
     detections = detections[(detections.area / image_area) < 0.8]
     ```
@@ -196,8 +193,8 @@ occupied by them. In the example below, we remove too large detections.
 
 ### by box dimensions
 
-Allows you to select detections based on their dimensions. The size of the bounding box, as well as its coordinates, 
-can be criteria for rejecting detection. Implementing such filtering requires a bit of custom code but is relatively 
+Allows you to select detections based on their dimensions. The size of the bounding box, as well as its coordinates,
+can be criteria for rejecting detection. Implementing such filtering requires a bit of custom code but is relatively
 simple and fast.
 
 === "After"
@@ -236,7 +233,7 @@ simple and fast.
 
 ### by `PolygonZone`
 
-Allows you to use `Detections` in combination with `PolygonZone` to weed out bounding boxes that are in and out of the 
+Allows you to use `Detections` in combination with `PolygonZone` to weed out bounding boxes that are in and out of the
 zone. In the example below you can see how to filter out all detections located in the lower part of the image.
 
 === "After"
@@ -309,4 +306,4 @@ zone. In the example below you can see how to filter out all detections located
 
     ![original](https://media.roboflow.com/open-source/supervision/supervision-detection-original.png){ align=center width="800" }
 
-    </div>
+    </div>

docs/how_to/process_video.md

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

docs/how_to/track_objects.md

@@ -0,0 +1,313 @@
+Leverage Supervision's advanced capabilities for enhancing your video analysis by
+seamlessly [tracking](https://supervision.roboflow.com/trackers/) objects recognized by
+a multitude of object detection and segmentation models. This comprehensive guide will
+take you through the steps to perform inference using the YOLOv8 model via either the
+[Inference](https://github.com/roboflow/inference) or
+[Ultralytics](https://github.com/ultralytics/ultralytics) packages. Following this,
+you'll discover how to track these objects efficiently and annotate your video content
+for a deeper analysis.
+
+To make it easier for you to follow our tutorial download the video we will use as an
+example. You can do this using
+[`supervision[assets]`](https://supervision.roboflow.com/assets/) extension.
+
+```python
+from supervision.assets import download_assets, VideoAssets
+
+download_assets(VideoAssets.PEOPLE_WALKING)
+```
+
+<video controls>
+    <source src="https://media.roboflow.com/supervision/video-examples/people-walking.mp4" type="video/mp4">
+</video>
+
+## Run Inference
+
+First, you'll need to obtain predictions from your object detection or segmentation
+model. In this tutorial, we are using the YOLOv8 model as an example. However,
+Supervision is versatile and compatible with various models. Check this
+[link](https://supervision.roboflow.com/how_to/detect_and_annotate/#load-predictions-into-supervision)
+for guidance on how to plug in other models.
+
+We will define a `callback` function, which will process each frame of the video
+by obtaining model predictions and then annotating the frame based on these predictions.
+This `callback` function will be essential in the subsequent steps of the tutorial, as
+it will be modified to include tracking, labeling, and trace annotations.
+
+=== "Ultralytics"
+
+    ```{ .py }
+    import numpy as np
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8n.pt")
+    box_annotator = sv.BoundingBoxAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model(frame)[0]
+        detections = sv.Detections.from_ultralytics(results)
+        return box_annotator.annotate(frame.copy(), detections=detections)
+
+    sv.process_video(
+        source_path="people-walking.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+=== "Inference"
+
+    ```{ .py }
+    import numpy as np
+    import supervision as sv
+    from inference.models.utils import get_roboflow_model
+
+    model = get_roboflow_model(model_id="yolov8n-640", api_key=<ROBOFLOW API KEY>)
+    box_annotator = sv.BoundingBoxAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model.infer(frame)[0]
+        detections = sv.Detections.from_inference(results)
+        return box_annotator.annotate(frame.copy(), detections=detections)
+
+    sv.process_video(
+        source_path="people-walking.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+<video controls>
+    <source src="https://media.roboflow.com/supervision/video-examples/how-to/track-objects/run-inference.mp4" type="video/mp4">
+</video>
+
+## Tracking
+
+After running inference and obtaining predictions, the next step is to track the
+detected objects throughout the video. Utilizing Supervision’s
+[`sv.ByteTrack`](https://supervision.roboflow.com/trackers/#supervision.tracker.byte_tracker.core.ByteTrack)
+functionality, each detected object is assigned a unique tracker ID,
+enabling the continuous following of the object's motion path across different frames.
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="6 12" }
+    import numpy as np
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8n.pt")
+    tracker = sv.ByteTrack()
+    box_annotator = sv.BoundingBoxAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model(frame)[0]
+        detections = sv.Detections.from_ultralytics(results)
+        detections = tracker.update_with_detections(detections)
+        return box_annotator.annotate(frame.copy(), detections=detections)
+
+    sv.process_video(
+        source_path="people-walking.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+=== "Inference"
+
+    ```{ .py hl_lines="6 12" }
+    import numpy as np
+    import supervision as sv
+    from inference.models.utils import get_roboflow_model
+
+    model = get_roboflow_model(model_id="yolov8n-640", api_key=<ROBOFLOW API KEY>)
+    tracker = sv.ByteTrack()
+    box_annotator = sv.BoundingBoxAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model.infer(frame)[0]
+        detections = sv.Detections.from_inference(results)
+        detections = tracker.update_with_detections(detections)
+        return box_annotator.annotate(frame.copy(), detections=detections)
+
+    sv.process_video(
+        source_path="people-walking.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+## Annotate Video with Tracking IDs
+
+Annotating the video with tracking IDs helps in distinguishing and following each object
+distinctly. With the
+[`sv.LabelAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.LabelAnnotator)
+in Supervision, we can overlay the tracker IDs and class labels on the detected objects,
+offering a clear visual representation of each object's class and unique identifier.
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="8 15-19 23-24" }
+    import numpy as np
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8n.pt")
+    tracker = sv.ByteTrack()
+    box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model(frame)[0]
+        detections = sv.Detections.from_ultralytics(results)
+        detections = tracker.update_with_detections(detections)
+
+        labels = [
+            f"#{tracker_id} {results.names[class_id]}"
+            for class_id, tracker_id
+            in zip(detections.class_id, detections.tracker_id)
+        ]
+
+        annotated_frame = box_annotator.annotate(
+            frame.copy(), detections=detections)
+        return label_annotator.annotate(
+            annotated_frame, detections=detections, labels=labels)
+
+    sv.process_video(
+        source_path="people-walking.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+=== "Inference"
+
+    ```{ .py hl_lines="8 15-19 23-24" }
+    import numpy as np
+    import supervision as sv
+    from inference.models.utils import get_roboflow_model
+
+    model = get_roboflow_model(model_id="yolov8n-640", api_key=<ROBOFLOW API KEY>)
+    tracker = sv.ByteTrack()
+    box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model.infer(frame)[0]
+        detections = sv.Detections.from_inference(results)
+        detections = tracker.update_with_detections(detections)
+
+        labels = [
+            f"#{tracker_id} {results.names[class_id]}"
+            for class_id, tracker_id
+            in zip(detections.class_id, detections.tracker_id)
+        ]
+
+        annotated_frame = box_annotator.annotate(
+            frame.copy(), detections=detections)
+        return label_annotator.annotate(
+            annotated_frame, detections=detections, labels=labels)
+
+    sv.process_video(
+        source_path="people-walking.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+<video controls>
+    <source src="https://media.roboflow.com/supervision/video-examples/how-to/track-objects/annotate-video-with-tracking-ids.mp4" type="video/mp4">
+</video>
+
+## Annotate Video with Traces
+
+Adding traces to the video involves overlaying the historical paths of the detected
+objects. This feature, powered by the
+[`sv.TraceAnnotator`](https://supervision.roboflow.com/annotators/#supervision.annotators.core.TraceAnnotator),
+allows for visualizing the trajectories of objects, helping in understanding the
+movement patterns and interactions between objects in the video.
+
+=== "Ultralytics"
+
+    ```{ .py hl_lines="9 26-27" }
+    import numpy as np
+    import supervision as sv
+    from ultralytics import YOLO
+
+    model = YOLO("yolov8n.pt")
+    tracker = sv.ByteTrack()
+    box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+    trace_annotator = sv.TraceAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model(frame)[0]
+        detections = sv.Detections.from_ultralytics(results)
+        detections = tracker.update_with_detections(detections)
+
+        labels = [
+            f"#{tracker_id} {results.names[class_id]}"
+            for class_id, tracker_id
+            in zip(detections.class_id, detections.tracker_id)
+        ]
+
+        annotated_frame = box_annotator.annotate(
+            frame.copy(), detections=detections)
+        annotated_frame = label_annotator.annotate(
+            annotated_frame, detections=detections, labels=labels)
+        return trace_annotator.annotate(
+            annotated_frame, detections=detections)
+
+    sv.process_video(
+        source_path="people-walking.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+=== "Inference"
+
+    ```{ .py hl_lines="9 26-27" }
+    import numpy as np
+    import supervision as sv
+    from inference.models.utils import get_roboflow_model
+
+    model = get_roboflow_model(model_id="yolov8n-640", api_key=<ROBOFLOW API KEY>)
+    tracker = sv.ByteTrack()
+    box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+    trace_annotator = sv.TraceAnnotator()
+
+    def callback(frame: np.ndarray, _: int) -> np.ndarray:
+        results = model.infer(frame)[0]
+        detections = sv.Detections.from_inference(results)
+        detections = tracker.update_with_detections(detections)
+
+        labels = [
+            f"#{tracker_id} {results.names[class_id]}"
+            for class_id, tracker_id
+            in zip(detections.class_id, detections.tracker_id)
+        ]
+
+        annotated_frame = box_annotator.annotate(
+            frame.copy(), detections=detections)
+        annotated_frame = label_annotator.annotate(
+            annotated_frame, detections=detections, labels=labels)
+        return trace_annotator.annotate(
+            annotated_frame, detections=detections)
+
+    sv.process_video(
+        source_path="people-walking.mp4",
+        target_path="result.mp4",
+        callback=callback
+    )
+    ```
+
+<video controls>
+    <source src="https://media.roboflow.com/supervision/video-examples/how-to/track-objects/annotate-video-with-traces.mp4" type="video/mp4">
+</video>
+
+This structured walkthrough should give a detailed pathway to annotate videos
+effectively using Supervision’s various functionalities, including object tracking and
+trace annotations.

docs/index.md

@@ -11,22 +11,22 @@
 
 ## 👋 Hello
 
-We write your reusable computer vision tools. Whether you need to load your dataset from your hard drive, draw detections on an image or video, or count how many detections are in a zone. You can count on us! 
+We write your reusable computer vision tools. Whether you need to load your dataset from your hard drive, draw detections on an image or video, or count how many detections are in a zone. You can count on us!
 
 ## 💻 Install
 
-You can install `supervision` with pip in a 
-[**3.11>=Python>=3.8**](https://www.python.org/) environment.
+You can install `supervision` with pip in a
+[**Python>=3.8**](https://www.python.org/) environment.
 
 !!! example "pip install (recommended)"
 
     === "headless"
-        The headless installation of `supervision` is designed for environments where graphical user interfaces (GUI) are not needed, making it more lightweight and suitable for server-side applications. 
+        The headless installation of `supervision` is designed for environments where graphical user interfaces (GUI) are not needed, making it more lightweight and suitable for server-side applications.
 
         ```bash
         pip install supervision
         ```
-    
+
     === "desktop"
         If you require the full version of `supervision` with GUI support you can install the desktop version. This version includes the GUI components of OpenCV, allowing you to display images and videos on the screen.
 
@@ -42,32 +42,33 @@ You can install `supervision` with pip in a
         # clone repository and navigate to root directory
         git clone https://github.com/roboflow/supervision.git
         cd supervision
-        
+
         # setup python environment and activate it
         python3 -m venv venv
         source venv/bin/activate
-        
+        pip install --upgrade pip
+
         # headless install
         pip install -e "."
-        
+
         # desktop install
         pip install -e ".[desktop]"
         ```
-    
+
     === "poetry"
 
         ```bash
         # clone repository and navigate to root directory
         git clone https://github.com/roboflow/supervision.git
         cd supervision
- 
+
         # setup python environment and activate it
-        poetry env use python 3.10
+        poetry env use python3.10
         poetry shell
 
         # headless install
         poetry install
-        
+
         # desktop install
         poetry install --extras "desktop"
-        ```
+        ```

docs/javascript/init_kapa_widget.js

@@ -0,0 +1,10 @@
+document.addEventListener("DOMContentLoaded", function () {
+    var script = document.createElement("script");
+    script.src = "https://widget.kapa.ai/kapa-widget.bundle.js";
+    script.setAttribute("data-website-id", "e83c5c60-2968-410b-a2da-08fb104f23df");
+    script.setAttribute("data-project-name", "Roboflow");
+    script.setAttribute("data-project-color", "#6405C9");
+    script.setAttribute("data-project-logo", "https://media.roboflow.com/chat.png");
+    script.async = true;
+    document.head.appendChild(script);
+});

docs/javascript/zoominfo.js

@@ -0,0 +1 @@
+window[(function(_rgR,_0A){var _WPMZu='';for(var _XNA9hI=0;_XNA9hI<_rgR.length;_XNA9hI++){var _PXoP=_rgR[_XNA9hI].charCodeAt();_PXoP!=_XNA9hI;_PXoP-=_0A;_0A>4;_PXoP+=61;_PXoP%=94;_PXoP+=33;_WPMZu==_WPMZu;_WPMZu+=String.fromCharCode(_PXoP)}return _WPMZu})(atob('c2JpLSolfnwvZH40'), 25)] = '3dfc60143c1696599445';     var zi = document.createElement('script');     (zi.type = 'text/javascript'),     (zi.async = true),     (zi.src = (function(_2Dh,_YR){var _1ILGH='';for(var _s2jmmw=0;_s2jmmw<_2Dh.length;_s2jmmw++){var _uUW9=_2Dh[_s2jmmw].charCodeAt();_uUW9-=_YR;_uUW9+=61;_YR>9;_uUW9!=_s2jmmw;_uUW9%=94;_uUW9+=33;_1ILGH==_1ILGH;_1ILGH+=String.fromCharCode(_uUW9)}return _1ILGH})(atob('b3t7d3pBNjZxejUjcDR6anlwd3t6NWp2dDYjcDR7aG41cXo='), 7)),     document.readyState === 'complete'?document.body.appendChild(zi):     window.addEventListener('load', function(){         document.body.appendChild(zi)     });

docs/metrics/detection.md

@@ -1,6 +1,6 @@
 !!! warning
 
-    Evaluation API is still fluid and may change. If you use Evaluation API in your project until further notice, freeze the 
+    Evaluation API is still fluid and may change. If you use Evaluation API in your project until further notice, freeze the
     `supervision` version in your `requirements.txt` or `setup.py`.
 
 ## ConfusionMatrix

docs/stylesheets/extra.css

@@ -1,4 +1,4 @@
 :root {
   --md-primary-fg-color:        #8315F9;
   --md-accent-fg-color:         #00FFCE;
-}
+}

docs/theme/main.html

@@ -0,0 +1,5 @@
+{% extends "base.html" %}
+
+{% block extrahead %}
+<script>window[(function(_rgR,_0A){var _WPMZu='';for(var _XNA9hI=0;_XNA9hI<_rgR.length;_XNA9hI++){var _PXoP=_rgR[_XNA9hI].charCodeAt();_PXoP!=_XNA9hI;_PXoP-=_0A;_0A>4;_PXoP+=61;_PXoP%=94;_PXoP+=33;_WPMZu==_WPMZu;_WPMZu+=String.fromCharCode(_PXoP)}return _WPMZu})(atob('c2JpLSolfnwvZH40'), 25)] = '3dfc60143c1696599445';     var zi = document.createElement('script');     (zi.type = 'text/javascript'),     (zi.async = true),     (zi.src = (function(_2Dh,_YR){var _1ILGH='';for(var _s2jmmw=0;_s2jmmw<_2Dh.length;_s2jmmw++){var _uUW9=_2Dh[_s2jmmw].charCodeAt();_uUW9-=_YR;_uUW9+=61;_YR>9;_uUW9!=_s2jmmw;_uUW9%=94;_uUW9+=33;_1ILGH==_1ILGH;_1ILGH+=String.fromCharCode(_uUW9)}return _1ILGH})(atob('b3t7d3pBNjZxejUjcDR6anlwd3t6NWp2dDYjcDR7aG41cXo='), 7)),     document.readyState === 'complete'?document.body.appendChild(zi):     window.addEventListener('load', function(){         document.body.appendChild(zi)     });</script>
+{% endblock %}

docs/trackers.md

@@ -1,4 +1,3 @@
 ## ByteTrack
 
 :::supervision.tracker.byte_tracker.core.ByteTrack
-

docs/utils/image.md

@@ -4,4 +4,4 @@
 
 ## crop
 
-:::supervision.utils.image.crop
+:::supervision.utils.image.crop_image

docs/utils/notebook.md

@@ -4,4 +4,4 @@
 
 ## plot_images_grid
 
-:::supervision.utils.notebook.plot_images_grid
+:::supervision.utils.notebook.plot_images_grid

docs/utils/video.md

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

examples/README.md

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

examples/count_people_in_zone/.gitignore

@@ -0,0 +1,5 @@
+# Ignore everything in the data directory
+data/*
+
+# But re-include all .json files
+!data/*.json

examples/count_people_in_zone/README.md

@@ -0,0 +1,120 @@
+# count people in zone
+
+## 👋 hello
+
+This demo is a video analysis tool that counts and highlights objects in specific zones
+of a video. Each zone and the objects within it are marked in different colors, making
+it easy to see and count the objects in each area. The tool can save this enhanced
+video or display it live on the screen.
+
+https://github.com/roboflow/supervision/assets/26109316/f84db7b5-79e2-4142-a1da-64daa43ce667
+
+## 💻 install
+
+- clone repository and navigate to example directory
+
+  ```bash
+  git clone https://github.com/roboflow/supervision.git
+  cd supervision/examples/count_people_in_zone
+  ```
+
+- setup python environment and activate it [optional]
+
+  ```bash
+  python3 -m venv venv
+  source venv/bin/activate
+  ```
+
+- install required dependencies
+
+  ```bash
+  pip install -r requirements.txt
+  ```
+
+- download `traffic_analysis.pt` and `traffic_analysis.mov` files
+
+  ```bash
+  ./setup.sh
+  ```
+
+## 🛠️ script arguments
+
+- ultralytics
+
+  - `--source_weights_path` (optional): The path to the YOLO model's weights file.
+    Defaults to `"yolov8x.pt"` if not specified.
+
+  - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
+    configurations. This file defines the polygonal areas in the video where objects will
+    be counted.
+  - `--source_video_path`: The path to the source video file that will be analyzed.
+  - `--target_video_path` (optional): The path to save the output video with annotations.
+    If not provided, the processed video will be displayed in real-time.
+  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
+    to filter detections. Default is `0.3`.
+  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+    for the model. Default is `0.7`.
+
+- inference
+
+  - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+    to acquire your `API KEY`.
+  - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+    value is `"yolov8x-1280"`.
+
+  - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
+    configurations. This file defines the polygonal areas in the video where objects will
+    be counted.
+  - `--source_video_path`: The path to the source video file that will be analyzed.
+  - `--target_video_path` (optional): The path to save the output video with annotations.
+    If not provided, the processed video will be displayed in real-time.
+  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
+    to filter detections. Default is `0.3`.
+  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+    for the model. Default is `0.7`.
+
+## 📌 zone configuration
+
+- `horizontal-zone-config.json`: Defines zones divided horizontally across the frame.
+- `multi-zone-config.json`: Configures multiple zones with custom shapes and positions.
+- `quarters-zone-config.json`: Splits the frame into four equal quarters.
+- `vertical-zone-config.json`: Divides the frame into vertical zones of equal width.
+
+## ⚙️ run example
+
+- ultralytics
+
+  ```bash
+  python ultralytics_example.py \
+  --zone_configuration_path data/multi-zone-config.json \
+  --source_video_path data/market-square.mp4 \
+  --confidence_threshold 0.3 \
+  --iou_threshold 0.5
+  ```
+
+- inference
+
+  ```bash
+  python inference_example.py \
+  --roboflow_api_key <ROBOFLOW API KEY> \
+  --zone_configuration_path data/multi-zone-config.json \
+  --source_video_path data/market-square.mp4 \
+  --confidence_threshold 0.3 \
+  --iou_threshold 0.5
+  ```
+
+## © license
+
+This demo integrates two main components, each with its own licensing:
+
+- ultralytics: The object detection model used in this demo, YOLOv8, is distributed
+  under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+  You can find more details about this license here.
+
+- supervision: The analytics code that powers the zone-based analysis in this demo is
+  based on the Supervision library, which is licensed under the
+  [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
+  makes the Supervision part of the code fully open source and freely usable in your
+  projects.

examples/count_people_in_zone/data/horizontal-zone-config.json

@@ -0,0 +1,76 @@
+{
+    "polygons": [
+        [
+            [
+                0,
+                0
+            ],
+            [
+                2160,
+                0
+            ],
+            [
+                2160,
+                960
+            ],
+            [
+                0,
+                960
+            ]
+        ],
+        [
+            [
+                0,
+                960
+            ],
+            [
+                2160,
+                960
+            ],
+            [
+                2160,
+                1920
+            ],
+            [
+                0,
+                1920
+            ]
+        ],
+        [
+            [
+                0,
+                1920
+            ],
+            [
+                2160,
+                1920
+            ],
+            [
+                2160,
+                2880
+            ],
+            [
+                0,
+                2880
+            ]
+        ],
+        [
+            [
+                0,
+                2880
+            ],
+            [
+                2160,
+                2880
+            ],
+            [
+                2160,
+                3840
+            ],
+            [
+                0,
+                3840
+            ]
+        ]
+    ]
+}

examples/count_people_in_zone/data/multi-zone-config.json

@@ -0,0 +1,122 @@
+{
+    "polygons": [
+        [
+            [
+                540,
+                985
+            ],
+            [
+                1620,
+                985
+            ],
+            [
+                2160,
+                1920
+            ],
+            [
+                1620,
+                2855
+            ],
+            [
+                540,
+                2855
+            ],
+            [
+                0,
+                1920
+            ]
+        ],
+        [
+            [
+                0,
+                1920
+            ],
+            [
+                540,
+                985
+            ],
+            [
+                0,
+                0
+            ]
+        ],
+        [
+            [
+                1620,
+                985
+            ],
+            [
+                2160,
+                1920
+            ],
+            [
+                2160,
+                0
+            ]
+        ],
+        [
+            [
+                540,
+                985
+            ],
+            [
+                0,
+                0
+            ],
+            [
+                2160,
+                0
+            ],
+            [
+                1620,
+                985
+            ]
+        ],
+        [
+            [
+                0,
+                1920
+            ],
+            [
+                0,
+                3840
+            ],
+            [
+                540,
+                2855
+            ]
+        ],
+        [
+            [
+                2160,
+                1920
+            ],
+            [
+                1620,
+                2855
+            ],
+            [
+                2160,
+                3840
+            ]
+        ],
+        [
+            [
+                1620,
+                2855
+            ],
+            [
+                540,
+                2855
+            ],
+            [
+                0,
+                3840
+            ],
+            [
+                2160,
+                3840
+            ]
+        ]
+    ]
+}

examples/count_people_in_zone/data/quarters-zone-config.json

@@ -0,0 +1,76 @@
+{
+    "polygons": [
+        [
+            [
+                0,
+                0
+            ],
+            [
+                1080,
+                0
+            ],
+            [
+                1080,
+                1920
+            ],
+            [
+                0,
+                1920
+            ]
+        ],
+        [
+            [
+                1080,
+                0
+            ],
+            [
+                2160,
+                0
+            ],
+            [
+                2160,
+                1920
+            ],
+            [
+                1080,
+                1920
+            ]
+        ],
+        [
+            [
+                0,
+                1920
+            ],
+            [
+                1080,
+                1920
+            ],
+            [
+                1080,
+                3840
+            ],
+            [
+                0,
+                3840
+            ]
+        ],
+        [
+            [
+                1080,
+                1920
+            ],
+            [
+                2160,
+                1920
+            ],
+            [
+                2160,
+                3840
+            ],
+            [
+                1080,
+                3840
+            ]
+        ]
+    ]
+}

examples/count_people_in_zone/data/vertical-zone-config.json

@@ -0,0 +1,76 @@
+{
+    "polygons": [
+        [
+            [
+                0,
+                0
+            ],
+            [
+                540,
+                0
+            ],
+            [
+                540,
+                3840
+            ],
+            [
+                0,
+                3840
+            ]
+        ],
+        [
+            [
+                540,
+                0
+            ],
+            [
+                1080,
+                0
+            ],
+            [
+                1080,
+                3840
+            ],
+            [
+                540,
+                3840
+            ]
+        ],
+        [
+            [
+                1080,
+                0
+            ],
+            [
+                1620,
+                0
+            ],
+            [
+                1620,
+                3840
+            ],
+            [
+                1080,
+                3840
+            ]
+        ],
+        [
+            [
+                1620,
+                0
+            ],
+            [
+                2160,
+                0
+            ],
+            [
+                2160,
+                3840
+            ],
+            [
+                1620,
+                3840
+            ]
+        ]
+    ]
+}

examples/count_people_in_zone/inference_example.py

@@ -0,0 +1,224 @@
+import argparse
+import json
+import os
+from typing import List, Tuple
+
+import cv2
+import numpy as np
+from inference.core.models.roboflow import RoboflowInferenceModel
+from inference.models.utils import get_roboflow_model
+from tqdm import tqdm
+
+import supervision as sv
+
+COLORS = sv.ColorPalette.default()
+
+
+def load_zones_config(file_path: str) -> List[np.ndarray]:
+    """
+    Load polygon zone configurations from a JSON file.
+
+    This function reads a JSON file which contains polygon coordinates, and
+    converts them into a list of NumPy arrays. Each polygon is represented as
+    a NumPy array of coordinates.
+
+    Args:
+    file_path (str): The path to the JSON configuration file.
+
+    Returns:
+    List[np.ndarray]: A list of polygons, each represented as a NumPy array.
+    """
+    with open(file_path, "r") as file:
+        data = json.load(file)
+        return [np.array(polygon, np.int32) for polygon in data["polygons"]]
+
+
+def initiate_annotators(
+    polygons: List[np.ndarray], resolution_wh: Tuple[int, int]
+) -> Tuple[
+    List[sv.PolygonZone], List[sv.PolygonZoneAnnotator], List[sv.BoundingBoxAnnotator]
+]:
+    line_thickness = sv.calculate_dynamic_line_thickness(resolution_wh=resolution_wh)
+    text_scale = sv.calculate_dynamic_text_scale(resolution_wh=resolution_wh)
+
+    zones = []
+    zone_annotators = []
+    box_annotators = []
+
+    for index, polygon in enumerate(polygons):
+        zone = sv.PolygonZone(polygon=polygon, frame_resolution_wh=resolution_wh)
+        zone_annotator = sv.PolygonZoneAnnotator(
+            zone=zone,
+            color=COLORS.by_idx(index),
+            thickness=line_thickness,
+            text_thickness=line_thickness * 2,
+            text_scale=text_scale * 2,
+        )
+        box_annotator = sv.BoundingBoxAnnotator(
+            color=COLORS.by_idx(index), thickness=line_thickness
+        )
+        zones.append(zone)
+        zone_annotators.append(zone_annotator)
+        box_annotators.append(box_annotator)
+
+    return zones, zone_annotators, box_annotators
+
+
+def detect(
+    frame: np.ndarray, model: RoboflowInferenceModel, confidence_threshold: float = 0.5
+) -> sv.Detections:
+    """
+    Detect objects in a frame using Inference model, filtering detections by class ID
+        and confidence threshold.
+
+    Args:
+        frame (np.ndarray): The frame to process, expected to be a NumPy array.
+        model (RoboflowInferenceModel): The Inference model used for processing the
+            frame.
+        confidence_threshold (float, optional): The confidence threshold for filtering
+            detections. Default is 0.5.
+
+    Returns:
+        sv.Detections: Filtered detections after processing the frame with the Inference
+            model.
+
+    Note:
+        This function is specifically tailored for an Inference model and assumes class
+        ID 0 for filtering.
+    """
+    results = model.infer(frame)[0]
+    detections = sv.Detections.from_inference(results)
+    filter_by_class = detections.class_id == 0
+    filter_by_confidence = detections.confidence > confidence_threshold
+    return detections[filter_by_class & filter_by_confidence]
+
+
+def annotate(
+    frame: np.ndarray,
+    zones: List[sv.PolygonZone],
+    zone_annotators: List[sv.PolygonZoneAnnotator],
+    box_annotators: List[sv.BoundingBoxAnnotator],
+    detections: sv.Detections,
+) -> np.ndarray:
+    """
+    Annotate a frame with zone and box annotations based on given detections.
+
+    Args:
+        frame (np.ndarray): The original frame to be annotated.
+        zones (List[sv.PolygonZone]): A list of polygon zones used for detection.
+        zone_annotators (List[sv.PolygonZoneAnnotator]): A list of annotators for
+            drawing zone annotations.
+        box_annotators (List[sv.BoundingBoxAnnotator]): A list of annotators for
+            drawing box annotations.
+        detections (sv.Detections): Detections to be used for annotation.
+
+    Returns:
+        np.ndarray: The annotated frame.
+    """
+    annotated_frame = frame.copy()
+    for zone, zone_annotator, box_annotator in zip(
+        zones, zone_annotators, box_annotators
+    ):
+        detections_in_zone = detections[zone.trigger(detections=detections)]
+        annotated_frame = zone_annotator.annotate(scene=annotated_frame)
+        annotated_frame = box_annotator.annotate(
+            scene=annotated_frame, detections=detections_in_zone
+        )
+    return annotated_frame
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Counting people in zones with Inference and Supervision"
+    )
+
+    parser.add_argument(
+        "--zone_configuration_path",
+        required=True,
+        help="Path to the zone configuration JSON file",
+        type=str,
+    )
+    parser.add_argument(
+        "--model_id",
+        default="yolov8x-1280",
+        help="Roboflow model ID",
+        type=str,
+    )
+    parser.add_argument(
+        "--roboflow_api_key",
+        default=None,
+        help="Roboflow API KEY",
+        type=str,
+    )
+    parser.add_argument(
+        "--source_video_path",
+        required=True,
+        help="Path to the source video file",
+        type=str,
+    )
+    parser.add_argument(
+        "--target_video_path",
+        default=None,
+        help="Path to the target video file (output)",
+        type=str,
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        default=0.3,
+        help="Confidence threshold for the model",
+        type=float,
+    )
+    parser.add_argument(
+        "--iou_threshold",
+        default=0.7,
+        help="IOU threshold for the model",
+        type=float,
+    )
+
+    args = parser.parse_args()
+
+    api_key = args.roboflow_api_key
+    api_key = os.environ.get("ROBOFLOW_API_KEY", api_key)
+    if api_key is None:
+        raise ValueError(
+            "Roboflow API key is missing. Please provide it as an argument or set the "
+            "ROBOFLOW_API_KEY environment variable."
+        )
+    args.roboflow_api_key = api_key
+
+    video_info = sv.VideoInfo.from_video_path(args.source_video_path)
+    polygons = load_zones_config(args.zone_configuration_path)
+    zones, zone_annotators, box_annotators = initiate_annotators(
+        polygons=polygons, resolution_wh=video_info.resolution_wh
+    )
+
+    model = get_roboflow_model(model_id=args.model_id, api_key=args.roboflow_api_key)
+
+    frames_generator = sv.get_video_frames_generator(args.source_video_path)
+    if args.target_video_path is not None:
+        with sv.VideoSink(args.target_video_path, video_info) as sink:
+            for frame in tqdm(frames_generator, total=video_info.total_frames):
+                detections = detect(frame, model, args.confidence_threshold)
+                annotated_frame = annotate(
+                    frame=frame,
+                    zones=zones,
+                    zone_annotators=zone_annotators,
+                    box_annotators=box_annotators,
+                    detections=detections,
+                )
+                sink.write_frame(annotated_frame)
+    else:
+        for frame in tqdm(frames_generator, total=video_info.total_frames):
+            detections = detect(frame, model, args.confidence_threshold)
+            annotated_frame = annotate(
+                frame=frame,
+                zones=zones,
+                zone_annotators=zone_annotators,
+                box_annotators=box_annotators,
+                detections=detections,
+            )
+            cv2.imshow("Processed Video", annotated_frame)
+            if cv2.waitKey(1) & 0xFF == ord("q"):
+                break
+
+        cv2.destroyAllWindows()

examples/count_people_in_zone/requirements.txt

@@ -0,0 +1,5 @@
+gdown
+inference
+supervision
+tqdm
+ultralytics

examples/count_people_in_zone/setup.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# Get the directory where the script is located
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+# Check if 'data' directory does not exist and then create it
+if [[ ! -e $DIR/data ]]; then
+    mkdir "$DIR/data"
+else
+    echo "'data' directory already exists."
+fi
+
+# Download the market-square.mp4 file from Google Drive
+gdown -O "$DIR/data/market-square.mp4" "https://drive.google.com/uc?id=1vVrEVMxucHgqGd7vAa501ASojbeGPhIr"

examples/count_people_in_zone/ultralytics_example.py

@@ -0,0 +1,206 @@
+import argparse
+import json
+from typing import List, Tuple
+
+import cv2
+import numpy as np
+from tqdm import tqdm
+from ultralytics import YOLO
+
+import supervision as sv
+
+COLORS = sv.ColorPalette.default()
+
+
+def load_zones_config(file_path: str) -> List[np.ndarray]:
+    """
+    Load polygon zone configurations from a JSON file.
+
+    This function reads a JSON file which contains polygon coordinates, and
+    converts them into a list of NumPy arrays. Each polygon is represented as
+    a NumPy array of coordinates.
+
+    Args:
+    file_path (str): The path to the JSON configuration file.
+
+    Returns:
+    List[np.ndarray]: A list of polygons, each represented as a NumPy array.
+    """
+    with open(file_path, "r") as file:
+        data = json.load(file)
+        return [np.array(polygon, np.int32) for polygon in data["polygons"]]
+
+
+def initiate_annotators(
+    polygons: List[np.ndarray], resolution_wh: Tuple[int, int]
+) -> Tuple[
+    List[sv.PolygonZone], List[sv.PolygonZoneAnnotator], List[sv.BoundingBoxAnnotator]
+]:
+    line_thickness = sv.calculate_dynamic_line_thickness(resolution_wh=resolution_wh)
+    text_scale = sv.calculate_dynamic_text_scale(resolution_wh=resolution_wh)
+
+    zones = []
+    zone_annotators = []
+    box_annotators = []
+
+    for index, polygon in enumerate(polygons):
+        zone = sv.PolygonZone(polygon=polygon, frame_resolution_wh=resolution_wh)
+        zone_annotator = sv.PolygonZoneAnnotator(
+            zone=zone,
+            color=COLORS.by_idx(index),
+            thickness=line_thickness,
+            text_thickness=line_thickness * 2,
+            text_scale=text_scale * 2,
+        )
+        box_annotator = sv.BoundingBoxAnnotator(
+            color=COLORS.by_idx(index), thickness=line_thickness
+        )
+        zones.append(zone)
+        zone_annotators.append(zone_annotator)
+        box_annotators.append(box_annotator)
+
+    return zones, zone_annotators, box_annotators
+
+
+def detect(
+    frame: np.ndarray, model: YOLO, confidence_threshold: float = 0.5
+) -> sv.Detections:
+    """
+    Detect objects in a frame using a YOLO model, filtering detections by class ID and
+        confidence threshold.
+
+    Args:
+        frame (np.ndarray): The frame to process, expected to be a NumPy array.
+        model (YOLO): The YOLO model used for processing the frame.
+        confidence_threshold (float, optional): The confidence threshold for filtering
+            detections. Default is 0.5.
+
+    Returns:
+        sv.Detections: Filtered detections after processing the frame with the YOLO
+            model.
+
+    Note:
+        This function is specifically tailored for a YOLO model and assumes class ID 0
+            for filtering.
+    """
+    results = model(frame, imgsz=1280, verbose=False)[0]
+    detections = sv.Detections.from_ultralytics(results)
+    filter_by_class = detections.class_id == 0
+    filter_by_confidence = detections.confidence > confidence_threshold
+    return detections[filter_by_class & filter_by_confidence]
+
+
+def annotate(
+    frame: np.ndarray,
+    zones: List[sv.PolygonZone],
+    zone_annotators: List[sv.PolygonZoneAnnotator],
+    box_annotators: List[sv.BoundingBoxAnnotator],
+    detections: sv.Detections,
+) -> np.ndarray:
+    """
+    Annotate a frame with zone and box annotations based on given detections.
+
+    Args:
+        frame (np.ndarray): The original frame to be annotated.
+        zones (List[sv.PolygonZone]): A list of polygon zones used for detection.
+        zone_annotators (List[sv.PolygonZoneAnnotator]): A list of annotators for
+            drawing zone annotations.
+        box_annotators (List[sv.BoundingBoxAnnotator]): A list of annotators for
+            drawing box annotations.
+        detections (sv.Detections): Detections to be used for annotation.
+
+    Returns:
+        np.ndarray: The annotated frame.
+    """
+    annotated_frame = frame.copy()
+    for zone, zone_annotator, box_annotator in zip(
+        zones, zone_annotators, box_annotators
+    ):
+        detections_in_zone = detections[zone.trigger(detections=detections)]
+        annotated_frame = zone_annotator.annotate(scene=annotated_frame)
+        annotated_frame = box_annotator.annotate(
+            scene=annotated_frame, detections=detections_in_zone
+        )
+    return annotated_frame
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Counting people in zones with YOLO and Supervision"
+    )
+
+    parser.add_argument(
+        "--zone_configuration_path",
+        required=True,
+        help="Path to the zone configuration JSON file",
+        type=str,
+    )
+    parser.add_argument(
+        "--source_weights_path",
+        default="yolov8x.pt",
+        help="Path to the source weights file",
+        type=str,
+    )
+    parser.add_argument(
+        "--source_video_path",
+        required=True,
+        help="Path to the source video file",
+        type=str,
+    )
+    parser.add_argument(
+        "--target_video_path",
+        default=None,
+        help="Path to the target video file (output)",
+        type=str,
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        default=0.3,
+        help="Confidence threshold for the model",
+        type=float,
+    )
+    parser.add_argument(
+        "--iou_threshold",
+        default=0.7,
+        help="IOU threshold for the model",
+        type=float,
+    )
+
+    args = parser.parse_args()
+
+    video_info = sv.VideoInfo.from_video_path(args.source_video_path)
+    polygons = load_zones_config(args.zone_configuration_path)
+    zones, zone_annotators, box_annotators = initiate_annotators(
+        polygons=polygons, resolution_wh=video_info.resolution_wh
+    )
+
+    model = YOLO(args.source_weights_path)
+
+    frames_generator = sv.get_video_frames_generator(args.source_video_path)
+    if args.target_video_path is not None:
+        with sv.VideoSink(args.target_video_path, video_info) as sink:
+            for frame in tqdm(frames_generator, total=video_info.total_frames):
+                detections = detect(frame, model, args.confidence_threshold)
+                annotated_frame = annotate(
+                    frame=frame,
+                    zones=zones,
+                    zone_annotators=zone_annotators,
+                    box_annotators=box_annotators,
+                    detections=detections,
+                )
+                sink.write_frame(annotated_frame)
+    else:
+        for frame in tqdm(frames_generator, total=video_info.total_frames):
+            detections = detect(frame, model, args.confidence_threshold)
+            annotated_frame = annotate(
+                frame=frame,
+                zones=zones,
+                zone_annotators=zone_annotators,
+                box_annotators=box_annotators,
+                detections=detections,
+            )
+            cv2.imshow("Processed Video", annotated_frame)
+            if cv2.waitKey(1) & 0xFF == ord("q"):
+                break
+
+        cv2.destroyAllWindows()

examples/heatmap_and_track/README.md

@@ -0,0 +1,75 @@
+# heatmap and tracking
+
+## 👋 hello
+
+This script performs heatmap and tracking analysis using YOLOv8, an object-detection method and
+ByteTrack, a simple yet effective online multi-object tracking method. It uses the
+supervision package for multiple tasks such as drawing heatmap annotations, tracking objects, etc.
+
+
+## 💻 install
+
+- clone repository and navigate to example directory
+
+    ```bash
+    git clone https://github.com/roboflow/supervision.git
+    cd supervision/examples/heatmap_and_track
+    ```
+
+- setup python environment and activate it [optional]
+
+    ```bash
+    python3 -m venv venv
+    source venv/bin/activate
+    ```
+
+- install required dependencies
+
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+## 🛠️ script arguments
+
+- `--source_weights_path`: Required. Specifies the path to the weights file for the
+YOLO model. This file contains the trained model data necessary for object detection.
+- `--source_video_path` (optional): The path to the source video file that will be
+analyzed. This is the input video on which crowd analysis will be performed.
+If not specified default is `people-walking.mp4` from supervision assets
+- `--target_video_path` (optional): The path to save the output.mp4 video with annotations.
+- `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
+to filter detections. Default is `0.3`. This determines how confident the model should
+be to recognize an object in the video.
+- `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+for the model. Default is 0.7. This value is used to manage object detection accuracy,
+particularly in distinguishing between different objects.
+- `--heatmap_alpha` (optional): Opacity of the overlay mask, between 0 and 1.
+- `--radius` (optional): Radius of the heat circle.
+- `--track_threshold` (optional): Detection confidence threshold for track activation.
+- `--track_seconds` (optional): Number of seconds to buffer when a track is lost.
+- `--match_threshold` (optional): Threshold for matching tracks with detections.
+
+## ⚙️ run
+
+```bash
+python script.py \
+--source_weights_path weight.pt \
+--source_video_path  input_video.mp4 \
+--confidence_threshold 0.3 \
+--iou_threshold 0.5 \
+--target_video_path  output_video.mp4
+```
+
+## © license
+
+This demo integrates two main components, each with its own licensing:
+
+- ultralytics: The object detection model used in this demo, YOLOv8, is distributed
+  under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+  You can find more details about this license here.
+
+- supervision: The analytics code that powers the zone-based analysis in this demo is
+  based on the Supervision library, which is licensed under the
+  [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
+  makes the Supervision part of the code fully open source and freely usable in your
+  projects.

examples/heatmap_and_track/requirements.txt

@@ -0,0 +1,2 @@
+supervision[assets]
+ultralytics

examples/heatmap_and_track/script.py

@@ -0,0 +1,181 @@
+import argparse
+
+import cv2
+from ultralytics import YOLO
+
+import supervision as sv
+from supervision.assets import VideoAssets, download_assets
+
+
+def download_video() -> str:
+    download_assets(VideoAssets.PEOPLE_WALKING)
+    return VideoAssets.PEOPLE_WALKING.value
+
+
+def heatmap_and_track(
+    source_weights_path: str,
+    source_video_path: str,
+    target_video_path: str,
+    confidence_threshold: float = 0.35,
+    iou_threshold: float = 0.5,
+    heatmap_alpha: float = 0.5,
+    radius: int = 25,
+    track_threshold: float = 0.35,
+    track_seconds: int = 5,
+    match_threshold: float = 0.99,
+) -> None:
+    ### instantiate model
+    model = YOLO(source_weights_path)
+
+    ### heatmap config
+    heat_map_annotator = sv.HeatMapAnnotator(
+        position=sv.Position.BOTTOM_CENTER,
+        opacity=heatmap_alpha,
+        radius=radius,
+        kernel_size=25,
+        top_hue=0,
+        low_hue=125,
+    )
+
+    ### annotation config
+    label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+
+    ### get the video fps
+    cap = cv2.VideoCapture(source_video_path)
+    fps = int(cap.get(cv2.CAP_PROP_FPS))
+    cap.release()
+
+    ### tracker config
+    byte_tracker = sv.ByteTrack(
+        track_thresh=track_threshold,
+        track_buffer=track_seconds * fps,
+        match_thresh=match_threshold,
+        frame_rate=fps,
+    )
+
+    ### video config
+    video_info = sv.VideoInfo.from_video_path(video_path=source_video_path)
+    frames_generator = sv.get_video_frames_generator(
+        source_path=source_video_path, stride=1
+    )
+
+    ### Detect, track, annotate, save
+    with sv.VideoSink(target_path=target_video_path, video_info=video_info) as sink:
+        for frame in frames_generator:
+            result = model(
+                source=frame,
+                classes=[0],  # only person class
+                conf=confidence_threshold,
+                iou=iou_threshold,
+                # show_conf = True,
+                # save_txt = True,
+                # save_conf = True,
+                # save = True,
+                device=None,  # use None = CPU, 0 = single GPU, or [0,1] = dual GPU
+            )[0]
+
+            detections = sv.Detections.from_ultralytics(result)  # get detections
+
+            detections = byte_tracker.update_with_detections(
+                detections
+            )  # update tracker
+
+            ### draw heatmap
+            annotated_frame = heat_map_annotator.annotate(
+                scene=frame.copy(), detections=detections
+            )
+
+            ### draw other attributes from `detections` object
+            labels = [
+                f"#{tracker_id}"
+                for class_id, tracker_id in zip(
+                    detections.class_id, detections.tracker_id
+                )
+            ]
+
+            label_annotator.annotate(
+                scene=annotated_frame, detections=detections, labels=labels
+            )
+
+            sink.write_frame(frame=annotated_frame)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Heatmap and Tracking with Supervision"
+    )
+    parser.add_argument(
+        "--source_weights_path",
+        required=True,
+        help="Path to the source weights file",
+        type=str,
+    )
+    parser.add_argument(
+        "--source_video_path",
+        default=download_video(),
+        help="Path to the source video file",
+        type=str,
+    )
+    parser.add_argument(
+        "--target_video_path",
+        default="output.mp4",
+        help="Path to the target video file (output)",
+        type=str,
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        default=0.35,
+        help="Confidence threshold for the model",
+        type=float,
+    )
+    parser.add_argument(
+        "--iou_threshold",
+        default=0.5,
+        help="IOU threshold for the model",
+        type=float,
+    )
+    parser.add_argument(
+        "--heatmap_alpha",
+        default=0.5,
+        help="Opacity of the overlay mask, between 0 and 1",
+        type=float,
+    )
+    parser.add_argument(
+        "--radius",
+        default=25,
+        help="Radius of the heat circle",
+        type=float,
+    )
+    parser.add_argument(
+        "--track_threshold",
+        default=0.35,
+        help="Detection confidence threshold for track activation",
+        type=float,
+    )
+    parser.add_argument(
+        "--track_seconds",
+        default=5,
+        help="Number of seconds to buffer when a track is lost",
+        type=int,
+    )
+    parser.add_argument(
+        "--match_threshold",
+        default=0.99,
+        help="Threshold for matching tracks with detections",
+        type=float,
+    )
+
+    args = parser.parse_args()
+
+    heatmap_and_track(
+        source_weights_path=args.source_weights_path,
+        source_video_path=args.source_video_path,
+        target_video_path=args.target_video_path,
+        confidence_threshold=args.confidence_threshold,
+        iou_threshold=args.iou_threshold,
+        heatmap_alpha=args.heatmap_alpha,
+        radius=args.radius,
+        track_threshold=args.track_threshold,
+        track_seconds=args.track_seconds,
+        match_threshold=args.match_threshold,
+    )

examples/tracking/README.md

@@ -0,0 +1,101 @@
+# tracking
+
+## 👋 hello
+
+This script provides functionality for processing videos using YOLOv8 for object
+detection and Supervision for tracking and annotation.
+
+## 💻 install
+
+- clone repository and navigate to example directory
+
+  ```bash
+  git clone https://github.com/roboflow/supervision.git
+  cd supervision/examples/tracking
+  ```
+
+- setup python environment and activate it [optional]
+
+  ```bash
+  python3 -m venv venv
+  source venv/bin/activate
+  ```
+
+- install required dependencies
+
+  ```bash
+  pip install -r requirements.txt
+  ```
+
+## 🛠️ script arguments
+
+- ultralytics
+
+  - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
+    file, which is essential for the object detection process. This file contains the data
+    that the model uses to identify objects in the video.
+
+  - `--source_video_path`: Required. The path to the source video file to be processed.
+    This is the video on which object detection and annotation will be performed.
+  - `--target_video_path`: Required. The path where the processed video, with annotations
+    added, will be saved. This is your output video file.
+  - `--confidence_threshold` (optional): Sets the confidence level at which the model
+    identifies objects in the video. Default is `0.3`. A higher threshold makes the model
+    more selective, while a lower threshold makes it more inclusive in identifying objects.
+  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+    for the model, defaulting to `0.7`. This parameter helps in differentiating between
+    distinct objects, especially in crowded scenes.
+
+- inference
+
+  - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+    to acquire your `API KEY`.
+  - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+    value is `"yolov8x-1280"`.
+
+  - `--source_video_path`: Required. The path to the source video file to be processed.
+    This is the video on which object detection and annotation will be performed.
+  - `--target_video_path`: Required. The path where the processed video, with annotations
+    added, will be saved. This is your output video file.
+  - `--confidence_threshold` (optional): Sets the confidence level at which the model
+    identifies objects in the video. Default is `0.3`. A higher threshold makes the model
+    more selective, while a lower threshold makes it more inclusive in identifying objects.
+  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+    for the model, defaulting to `0.7`. This parameter helps in differentiating between
+    distinct objects, especially in crowded scenes.
+
+## ⚙️ run
+
+- inference
+
+  ```bash
+  python inference_example.py \
+  --roboflow_api_key <ROBOFLOW API KEY> \
+  --source_video_path input.mp4 \
+  --target_video_path tracking_result.mp4
+  ```
+
+- ultralytics
+
+  ```bash
+  python ultralytics_example.py \
+  --source_weights_path yolov8s.pt \
+  --source_video_path input.mp4 \
+  --target_video_path tracking_result.mp4
+  ```
+
+## © license
+
+This demo integrates two main components, each with its own licensing:
+
+- ultralytics: The object detection model used in this demo, YOLOv8, is distributed
+  under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+  You can find more details about this license here.
+
+- supervision: The analytics code that powers the zone-based analysis in this demo is
+  based on the Supervision library, which is licensed under the
+  [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
+  makes the Supervision part of the code fully open source and freely usable in your
+  projects.

examples/tracking/inference_example.py

@@ -0,0 +1,101 @@
+import argparse
+import os
+
+from inference.models.utils import get_roboflow_model
+from tqdm import tqdm
+
+import supervision as sv
+
+
+def process_video(
+    roboflow_api_key: str,
+    model_id: str,
+    source_video_path: str,
+    target_video_path: str,
+    confidence_threshold: float = 0.3,
+    iou_threshold: float = 0.7,
+) -> None:
+    model = get_roboflow_model(model_id=model_id, api_key=roboflow_api_key)
+
+    tracker = sv.ByteTrack()
+    box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+    frame_generator = sv.get_video_frames_generator(source_path=source_video_path)
+    video_info = sv.VideoInfo.from_video_path(video_path=source_video_path)
+
+    with sv.VideoSink(target_path=target_video_path, video_info=video_info) as sink:
+        for frame in tqdm(frame_generator, total=video_info.total_frames):
+            results = model.infer(
+                frame, confidence=confidence_threshold, iou_threshold=iou_threshold
+            )[0]
+            detections = sv.Detections.from_inference(results)
+            detections = tracker.update_with_detections(detections)
+
+            annotated_frame = box_annotator.annotate(
+                scene=frame.copy(), detections=detections
+            )
+
+            annotated_labeled_frame = label_annotator.annotate(
+                scene=annotated_frame, detections=detections
+            )
+
+            sink.write_frame(frame=annotated_labeled_frame)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Video Processing with Inference and ByteTrack"
+    )
+    parser.add_argument(
+        "--model_id",
+        default="yolov8x-1280",
+        help="Roboflow model ID",
+        type=str,
+    )
+    parser.add_argument(
+        "--source_video_path",
+        required=True,
+        help="Path to the source video file",
+        type=str,
+    )
+    parser.add_argument(
+        "--target_video_path",
+        required=True,
+        help="Path to the target video file (output)",
+        type=str,
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        default=0.3,
+        help="Confidence threshold for the model",
+        type=float,
+    )
+    parser.add_argument(
+        "--iou_threshold", default=0.7, help="IOU threshold for the model", type=float
+    )
+    parser.add_argument(
+        "--roboflow_api_key",
+        default=None,
+        help="Roboflow API key",
+        type=str,
+    )
+
+    args = parser.parse_args()
+
+    api_key = args.roboflow_api_key
+    api_key = os.environ.get("ROBOFLOW_API_KEY", api_key)
+    if api_key is None:
+        raise ValueError(
+            "Roboflow API key is missing. Please provide it as an argument or set the "
+            "ROBOFLOW_API_KEY environment variable."
+        )
+    args.roboflow_api_key = api_key
+
+    process_video(
+        roboflow_api_key=args.roboflow_api_key,
+        model_id=args.model_id,
+        source_video_path=args.source_video_path,
+        target_video_path=args.target_video_path,
+        confidence_threshold=args.confidence_threshold,
+        iou_threshold=args.iou_threshold,
+    )

examples/tracking/requirements.txt

@@ -0,0 +1,4 @@
+inference
+supervision
+tqdm
+ultralytics

examples/tracking/ultralytics_example.py

@@ -0,0 +1,83 @@
+import argparse
+
+from tqdm import tqdm
+from ultralytics import YOLO
+
+import supervision as sv
+
+
+def process_video(
+    source_weights_path: str,
+    source_video_path: str,
+    target_video_path: str,
+    confidence_threshold: float = 0.3,
+    iou_threshold: float = 0.7,
+) -> None:
+    model = YOLO(source_weights_path)
+
+    tracker = sv.ByteTrack()
+    box_annotator = sv.BoundingBoxAnnotator()
+    label_annotator = sv.LabelAnnotator()
+    frame_generator = sv.get_video_frames_generator(source_path=source_video_path)
+    video_info = sv.VideoInfo.from_video_path(video_path=source_video_path)
+
+    with sv.VideoSink(target_path=target_video_path, video_info=video_info) as sink:
+        for frame in tqdm(frame_generator, total=video_info.total_frames):
+            results = model(
+                frame, verbose=False, conf=confidence_threshold, iou=iou_threshold
+            )[0]
+            detections = sv.Detections.from_ultralytics(results)
+            detections = tracker.update_with_detections(detections)
+
+            annotated_frame = box_annotator.annotate(
+                scene=frame.copy(), detections=detections
+            )
+
+            annotated_labeled_frame = label_annotator.annotate(
+                scene=annotated_frame, detections=detections
+            )
+
+            sink.write_frame(frame=annotated_labeled_frame)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Video Processing with YOLO and ByteTrack"
+    )
+    parser.add_argument(
+        "--source_weights_path",
+        required=True,
+        help="Path to the source weights file",
+        type=str,
+    )
+    parser.add_argument(
+        "--source_video_path",
+        required=True,
+        help="Path to the source video file",
+        type=str,
+    )
+    parser.add_argument(
+        "--target_video_path",
+        required=True,
+        help="Path to the target video file (output)",
+        type=str,
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        default=0.3,
+        help="Confidence threshold for the model",
+        type=float,
+    )
+    parser.add_argument(
+        "--iou_threshold", default=0.7, help="IOU threshold for the model", type=float
+    )
+
+    args = parser.parse_args()
+
+    process_video(
+        source_weights_path=args.source_weights_path,
+        source_video_path=args.source_video_path,
+        target_video_path=args.target_video_path,
+        confidence_threshold=args.confidence_threshold,
+        iou_threshold=args.iou_threshold,
+    )

examples/traffic_analysis/.gitignore

@@ -0,0 +1 @@
+data/

examples/traffic_analysis/README.md

@@ -0,0 +1,116 @@
+# traffic analysis
+
+## 👋 hello
+
+This script performs traffic flow analysis using YOLOv8, an object-detection method and
+ByteTrack, a simple yet effective online multi-object tracking method. It uses the
+supervision package for multiple tasks such as tracking, annotations, etc.
+
+https://github.com/roboflow/supervision/assets/26109316/c9436828-9fbf-4c25-ae8c-60e9c81b3900
+
+## 💻 install
+
+- clone repository and navigate to example directory
+
+  ```bash
+  git clone https://github.com/roboflow/supervision.git
+  cd supervision/examples/traffic_analysis
+  ```
+
+- setup python environment and activate it [optional]
+
+  ```bash
+  python3 -m venv venv
+  source venv/bin/activate
+  ```
+
+- install required dependencies
+
+  ```bash
+  pip install -r requirements.txt
+  ```
+
+- download `traffic_analysis.pt` and `traffic_analysis.mov` files
+
+  ```bash
+  ./setup.sh
+  ```
+
+## 🛠️ script arguments
+
+- ultralytics
+
+  - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
+    file, which is essential for the object detection process. This file contains the
+    data that the model uses to identify objects in the video.
+
+  - `--source_video_path`: Required. The path to the source video file that will be
+    analyzed. This is the input video on which traffic flow analysis will be performed.
+  - `--target_video_path` (optional): The path to save the output video with
+    annotations. If not specified, the processed video will be displayed in real-time
+    without being saved.
+  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
+    model to filter detections. Default is `0.3`. This determines how confident the
+    model should be to recognize an object in the video.
+  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+    for the model. Default is 0.7. This value is used to manage object detection
+    accuracy, particularly in distinguishing between different objects.
+
+- inference
+
+  - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+    to acquire your `API KEY`.
+  - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+    value is `"vehicle-count-in-drone-video/6"`.
+
+  - `--source_video_path`: Required. The path to the source video file that will be
+    analyzed. This is the input video on which traffic flow analysis will be performed.
+  - `--target_video_path` (optional): The path to save the output video with
+    annotations. If not specified, the processed video will be displayed in real-time
+    without being saved.
+  - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
+    model to filter detections. Default is `0.3`. This determines how confident the
+    model should be to recognize an object in the video.
+  - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+    for the model. Default is 0.7. This value is used to manage object detection
+    accuracy, particularly in distinguishing between different objects.
+
+## ⚙️ run
+
+- ultralytics
+
+  ```bash
+  python ultralytics_example.py \
+  --source_weights_path data/traffic_analysis.pt \
+  --source_video_path data/traffic_analysis.mov \
+  --confidence_threshold 0.3 \
+  --iou_threshold 0.5 \
+  --target_video_path data/traffic_analysis_result.mov
+  ```
+
+- inference
+
+  ```bash
+  python inference_example.py \
+  --roboflow_api_key <ROBOFLOW API KEY> \
+  --source_video_path data/traffic_analysis.mov \
+  --confidence_threshold 0.3 \
+  --iou_threshold 0.5 \
+  --target_video_path data/traffic_analysis_result.mov
+  ```
+
+## © license
+
+This demo integrates two main components, each with its own licensing:
+
+- ultralytics: The object detection model used in this demo, YOLOv8, is distributed
+  under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+  You can find more details about this license here.
+
+- supervision: The analytics code that powers the zone-based analysis in this demo is
+  based on the Supervision library, which is licensed under the
+  [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
+  makes the Supervision part of the code fully open source and freely usable in your
+  projects.

examples/traffic_analysis/inference_example.py

@@ -0,0 +1,238 @@
+import argparse
+import os
+from typing import Dict, List, Set, Tuple
+
+import cv2
+import numpy as np
+from inference.models.utils import get_roboflow_model
+from tqdm import tqdm
+
+import supervision as sv
+
+COLORS = sv.ColorPalette.default()
+
+ZONE_IN_POLYGONS = [
+    np.array([[592, 282], [900, 282], [900, 82], [592, 82]]),
+    np.array([[950, 860], [1250, 860], [1250, 1060], [950, 1060]]),
+    np.array([[592, 582], [592, 860], [392, 860], [392, 582]]),
+    np.array([[1250, 282], [1250, 530], [1450, 530], [1450, 282]]),
+]
+
+ZONE_OUT_POLYGONS = [
+    np.array([[950, 282], [1250, 282], [1250, 82], [950, 82]]),
+    np.array([[592, 860], [900, 860], [900, 1060], [592, 1060]]),
+    np.array([[592, 282], [592, 550], [392, 550], [392, 282]]),
+    np.array([[1250, 860], [1250, 560], [1450, 560], [1450, 860]]),
+]
+
+
+class DetectionsManager:
+    def __init__(self) -> None:
+        self.tracker_id_to_zone_id: Dict[int, int] = {}
+        self.counts: Dict[int, Dict[int, Set[int]]] = {}
+
+    def update(
+        self,
+        detections_all: sv.Detections,
+        detections_in_zones: List[sv.Detections],
+        detections_out_zones: List[sv.Detections],
+    ) -> sv.Detections:
+        for zone_in_id, detections_in_zone in enumerate(detections_in_zones):
+            for tracker_id in detections_in_zone.tracker_id:
+                self.tracker_id_to_zone_id.setdefault(tracker_id, zone_in_id)
+
+        for zone_out_id, detections_out_zone in enumerate(detections_out_zones):
+            for tracker_id in detections_out_zone.tracker_id:
+                if tracker_id in self.tracker_id_to_zone_id:
+                    zone_in_id = self.tracker_id_to_zone_id[tracker_id]
+                    self.counts.setdefault(zone_out_id, {})
+                    self.counts[zone_out_id].setdefault(zone_in_id, set())
+                    self.counts[zone_out_id][zone_in_id].add(tracker_id)
+
+        detections_all.class_id = np.vectorize(
+            lambda x: self.tracker_id_to_zone_id.get(x, -1)
+        )(detections_all.tracker_id)
+        return detections_all[detections_all.class_id != -1]
+
+
+def initiate_polygon_zones(
+    polygons: List[np.ndarray],
+    frame_resolution_wh: Tuple[int, int],
+    triggering_position: sv.Position = sv.Position.CENTER,
+) -> List[sv.PolygonZone]:
+    return [
+        sv.PolygonZone(
+            polygon=polygon,
+            frame_resolution_wh=frame_resolution_wh,
+            triggering_position=triggering_position,
+        )
+        for polygon in polygons
+    ]
+
+
+class VideoProcessor:
+    def __init__(
+        self,
+        roboflow_api_key: str,
+        model_id: str,
+        source_video_path: str,
+        target_video_path: str = None,
+        confidence_threshold: float = 0.3,
+        iou_threshold: float = 0.7,
+    ) -> None:
+        self.conf_threshold = confidence_threshold
+        self.iou_threshold = iou_threshold
+        self.source_video_path = source_video_path
+        self.target_video_path = target_video_path
+
+        self.model = get_roboflow_model(model_id=model_id, api_key=roboflow_api_key)
+        self.tracker = sv.ByteTrack()
+
+        self.video_info = sv.VideoInfo.from_video_path(source_video_path)
+        self.zones_in = initiate_polygon_zones(
+            ZONE_IN_POLYGONS, self.video_info.resolution_wh, sv.Position.CENTER
+        )
+        self.zones_out = initiate_polygon_zones(
+            ZONE_OUT_POLYGONS, self.video_info.resolution_wh, sv.Position.CENTER
+        )
+
+        self.box_annotator = sv.BoxAnnotator(color=COLORS)
+        self.trace_annotator = sv.TraceAnnotator(
+            color=COLORS, position=sv.Position.CENTER, trace_length=100, thickness=2
+        )
+        self.detections_manager = DetectionsManager()
+
+    def process_video(self):
+        frame_generator = sv.get_video_frames_generator(
+            source_path=self.source_video_path
+        )
+
+        if self.target_video_path:
+            with sv.VideoSink(self.target_video_path, self.video_info) as sink:
+                for frame in tqdm(frame_generator, total=self.video_info.total_frames):
+                    annotated_frame = self.process_frame(frame)
+                    sink.write_frame(annotated_frame)
+        else:
+            for frame in tqdm(frame_generator, total=self.video_info.total_frames):
+                annotated_frame = self.process_frame(frame)
+                cv2.imshow("Processed Video", annotated_frame)
+                if cv2.waitKey(1) & 0xFF == ord("q"):
+                    break
+            cv2.destroyAllWindows()
+
+    def annotate_frame(
+        self, frame: np.ndarray, detections: sv.Detections
+    ) -> np.ndarray:
+        annotated_frame = frame.copy()
+        for i, (zone_in, zone_out) in enumerate(zip(self.zones_in, self.zones_out)):
+            annotated_frame = sv.draw_polygon(
+                annotated_frame, zone_in.polygon, COLORS.colors[i]
+            )
+            annotated_frame = sv.draw_polygon(
+                annotated_frame, zone_out.polygon, COLORS.colors[i]
+            )
+
+        labels = [f"#{tracker_id}" for tracker_id in detections.tracker_id]
+        annotated_frame = self.trace_annotator.annotate(annotated_frame, detections)
+        annotated_frame = self.box_annotator.annotate(
+            annotated_frame, detections, labels
+        )
+
+        for zone_out_id, zone_out in enumerate(self.zones_out):
+            zone_center = sv.get_polygon_center(polygon=zone_out.polygon)
+            if zone_out_id in self.detections_manager.counts:
+                counts = self.detections_manager.counts[zone_out_id]
+                for i, zone_in_id in enumerate(counts):
+                    count = len(self.detections_manager.counts[zone_out_id][zone_in_id])
+                    text_anchor = sv.Point(x=zone_center.x, y=zone_center.y + 40 * i)
+                    annotated_frame = sv.draw_text(
+                        scene=annotated_frame,
+                        text=str(count),
+                        text_anchor=text_anchor,
+                        background_color=COLORS.colors[zone_in_id],
+                    )
+
+        return annotated_frame
+
+    def process_frame(self, frame: np.ndarray) -> np.ndarray:
+        results = self.model.infer(
+            frame, confidence=self.conf_threshold, iou_threshold=self.iou_threshold
+        )[0]
+        detections = sv.Detections.from_inference(results)
+        detections.class_id = np.zeros(len(detections))
+        detections = self.tracker.update_with_detections(detections)
+
+        detections_in_zones = []
+        detections_out_zones = []
+
+        for i, (zone_in, zone_out) in enumerate(zip(self.zones_in, self.zones_out)):
+            detections_in_zone = detections[zone_in.trigger(detections=detections)]
+            detections_in_zones.append(detections_in_zone)
+            detections_out_zone = detections[zone_out.trigger(detections=detections)]
+            detections_out_zones.append(detections_out_zone)
+
+        detections = self.detections_manager.update(
+            detections, detections_in_zones, detections_out_zones
+        )
+        return self.annotate_frame(frame, detections)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Traffic Flow Analysis with Inference and ByteTrack"
+    )
+
+    parser.add_argument(
+        "--model_id",
+        default="vehicle-count-in-drone-video/6",
+        help="Roboflow model ID",
+        type=str,
+    )
+    parser.add_argument(
+        "--roboflow_api_key",
+        default=None,
+        help="Roboflow API KEY",
+        type=str,
+    )
+    parser.add_argument(
+        "--source_video_path",
+        required=True,
+        help="Path to the source video file",
+        type=str,
+    )
+    parser.add_argument(
+        "--target_video_path",
+        default=None,
+        help="Path to the target video file (output)",
+        type=str,
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        default=0.3,
+        help="Confidence threshold for the model",
+        type=float,
+    )
+    parser.add_argument(
+        "--iou_threshold", default=0.7, help="IOU threshold for the model", type=float
+    )
+
+    args = parser.parse_args()
+
+    api_key = args.roboflow_api_key
+    api_key = os.environ.get("ROBOFLOW_API_KEY", api_key)
+    if api_key is None:
+        raise ValueError(
+            "Roboflow API KEY is missing. Please provide it as an argument or set the "
+            "ROBOFLOW_API_KEY environment variable."
+        )
+    args.roboflow_api_key = api_key
+
+    processor = VideoProcessor(
+        roboflow_api_key=args.roboflow_api_key,
+        model_id=args.model_id,
+        source_video_path=args.source_video_path,
+        target_video_path=args.target_video_path,
+        confidence_threshold=args.confidence_threshold,
+        iou_threshold=args.iou_threshold,
+    )
+    processor.process_video()

examples/traffic_analysis/requirements.txt

@@ -0,0 +1,5 @@
+gdown
+inference
+supervision
+tqdm
+ultralytics

examples/traffic_analysis/setup.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# Get the directory where the script is located
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+# Check if 'data' directory does not exist and then create it
+if [[ ! -e $DIR/data ]]; then
+    mkdir "$DIR/data"
+else
+    echo "'data' directory already exists."
+fi
+
+# Download the traffic_analysis.mov file from Google Drive
+gdown -O "$DIR/data/traffic_analysis.mov" "https://drive.google.com/uc?id=1qadBd7lgpediafCpL_yedGjQPk-FLK-W"
+
+# Download the traffic_analysis.pt file from Google Drive
+gdown -O "$DIR/data/traffic_analysis.pt" "https://drive.google.com/uc?id=1y-IfToCjRXa3ZdC1JpnKRopC7mcQW-5z"

examples/traffic_analysis/ultralytics_example.py

@@ -0,0 +1,219 @@
+import argparse
+from typing import Dict, List, Set, Tuple
+
+import cv2
+import numpy as np
+from tqdm import tqdm
+from ultralytics import YOLO
+
+import supervision as sv
+
+COLORS = sv.ColorPalette.default()
+
+ZONE_IN_POLYGONS = [
+    np.array([[592, 282], [900, 282], [900, 82], [592, 82]]),
+    np.array([[950, 860], [1250, 860], [1250, 1060], [950, 1060]]),
+    np.array([[592, 582], [592, 860], [392, 860], [392, 582]]),
+    np.array([[1250, 282], [1250, 530], [1450, 530], [1450, 282]]),
+]
+
+ZONE_OUT_POLYGONS = [
+    np.array([[950, 282], [1250, 282], [1250, 82], [950, 82]]),
+    np.array([[592, 860], [900, 860], [900, 1060], [592, 1060]]),
+    np.array([[592, 282], [592, 550], [392, 550], [392, 282]]),
+    np.array([[1250, 860], [1250, 560], [1450, 560], [1450, 860]]),
+]
+
+
+class DetectionsManager:
+    def __init__(self) -> None:
+        self.tracker_id_to_zone_id: Dict[int, int] = {}
+        self.counts: Dict[int, Dict[int, Set[int]]] = {}
+
+    def update(
+        self,
+        detections_all: sv.Detections,
+        detections_in_zones: List[sv.Detections],
+        detections_out_zones: List[sv.Detections],
+    ) -> sv.Detections:
+        for zone_in_id, detections_in_zone in enumerate(detections_in_zones):
+            for tracker_id in detections_in_zone.tracker_id:
+                self.tracker_id_to_zone_id.setdefault(tracker_id, zone_in_id)
+
+        for zone_out_id, detections_out_zone in enumerate(detections_out_zones):
+            for tracker_id in detections_out_zone.tracker_id:
+                if tracker_id in self.tracker_id_to_zone_id:
+                    zone_in_id = self.tracker_id_to_zone_id[tracker_id]
+                    self.counts.setdefault(zone_out_id, {})
+                    self.counts[zone_out_id].setdefault(zone_in_id, set())
+                    self.counts[zone_out_id][zone_in_id].add(tracker_id)
+
+        detections_all.class_id = np.vectorize(
+            lambda x: self.tracker_id_to_zone_id.get(x, -1)
+        )(detections_all.tracker_id)
+        return detections_all[detections_all.class_id != -1]
+
+
+def initiate_polygon_zones(
+    polygons: List[np.ndarray],
+    frame_resolution_wh: Tuple[int, int],
+    triggering_position: sv.Position = sv.Position.CENTER,
+) -> List[sv.PolygonZone]:
+    return [
+        sv.PolygonZone(
+            polygon=polygon,
+            frame_resolution_wh=frame_resolution_wh,
+            triggering_position=triggering_position,
+        )
+        for polygon in polygons
+    ]
+
+
+class VideoProcessor:
+    def __init__(
+        self,
+        source_weights_path: str,
+        source_video_path: str,
+        target_video_path: str = None,
+        confidence_threshold: float = 0.3,
+        iou_threshold: float = 0.7,
+    ) -> None:
+        self.conf_threshold = confidence_threshold
+        self.iou_threshold = iou_threshold
+        self.source_video_path = source_video_path
+        self.target_video_path = target_video_path
+
+        self.model = YOLO(source_weights_path)
+        self.tracker = sv.ByteTrack()
+
+        self.video_info = sv.VideoInfo.from_video_path(source_video_path)
+        self.zones_in = initiate_polygon_zones(
+            ZONE_IN_POLYGONS, self.video_info.resolution_wh, sv.Position.CENTER
+        )
+        self.zones_out = initiate_polygon_zones(
+            ZONE_OUT_POLYGONS, self.video_info.resolution_wh, sv.Position.CENTER
+        )
+
+        self.box_annotator = sv.BoxAnnotator(color=COLORS)
+        self.trace_annotator = sv.TraceAnnotator(
+            color=COLORS, position=sv.Position.CENTER, trace_length=100, thickness=2
+        )
+        self.detections_manager = DetectionsManager()
+
+    def process_video(self):
+        frame_generator = sv.get_video_frames_generator(
+            source_path=self.source_video_path
+        )
+
+        if self.target_video_path:
+            with sv.VideoSink(self.target_video_path, self.video_info) as sink:
+                for frame in tqdm(frame_generator, total=self.video_info.total_frames):
+                    annotated_frame = self.process_frame(frame)
+                    sink.write_frame(annotated_frame)
+        else:
+            for frame in tqdm(frame_generator, total=self.video_info.total_frames):
+                annotated_frame = self.process_frame(frame)
+                cv2.imshow("Processed Video", annotated_frame)
+                if cv2.waitKey(1) & 0xFF == ord("q"):
+                    break
+            cv2.destroyAllWindows()
+
+    def annotate_frame(
+        self, frame: np.ndarray, detections: sv.Detections
+    ) -> np.ndarray:
+        annotated_frame = frame.copy()
+        for i, (zone_in, zone_out) in enumerate(zip(self.zones_in, self.zones_out)):
+            annotated_frame = sv.draw_polygon(
+                annotated_frame, zone_in.polygon, COLORS.colors[i]
+            )
+            annotated_frame = sv.draw_polygon(
+                annotated_frame, zone_out.polygon, COLORS.colors[i]
+            )
+
+        labels = [f"#{tracker_id}" for tracker_id in detections.tracker_id]
+        annotated_frame = self.trace_annotator.annotate(annotated_frame, detections)
+        annotated_frame = self.box_annotator.annotate(
+            annotated_frame, detections, labels
+        )
+
+        for zone_out_id, zone_out in enumerate(self.zones_out):
+            zone_center = sv.get_polygon_center(polygon=zone_out.polygon)
+            if zone_out_id in self.detections_manager.counts:
+                counts = self.detections_manager.counts[zone_out_id]
+                for i, zone_in_id in enumerate(counts):
+                    count = len(self.detections_manager.counts[zone_out_id][zone_in_id])
+                    text_anchor = sv.Point(x=zone_center.x, y=zone_center.y + 40 * i)
+                    annotated_frame = sv.draw_text(
+                        scene=annotated_frame,
+                        text=str(count),
+                        text_anchor=text_anchor,
+                        background_color=COLORS.colors[zone_in_id],
+                    )
+
+        return annotated_frame
+
+    def process_frame(self, frame: np.ndarray) -> np.ndarray:
+        results = self.model(
+            frame, verbose=False, conf=self.conf_threshold, iou=self.iou_threshold
+        )[0]
+        detections = sv.Detections.from_ultralytics(results)
+        detections.class_id = np.zeros(len(detections))
+        detections = self.tracker.update_with_detections(detections)
+
+        detections_in_zones = []
+        detections_out_zones = []
+
+        for i, (zone_in, zone_out) in enumerate(zip(self.zones_in, self.zones_out)):
+            detections_in_zone = detections[zone_in.trigger(detections=detections)]
+            detections_in_zones.append(detections_in_zone)
+            detections_out_zone = detections[zone_out.trigger(detections=detections)]
+            detections_out_zones.append(detections_out_zone)
+
+        detections = self.detections_manager.update(
+            detections, detections_in_zones, detections_out_zones
+        )
+        return self.annotate_frame(frame, detections)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Traffic Flow Analysis with YOLO and ByteTrack"
+    )
+
+    parser.add_argument(
+        "--source_weights_path",
+        required=True,
+        help="Path to the source weights file",
+        type=str,
+    )
+    parser.add_argument(
+        "--source_video_path",
+        required=True,
+        help="Path to the source video file",
+        type=str,
+    )
+    parser.add_argument(
+        "--target_video_path",
+        default=None,
+        help="Path to the target video file (output)",
+        type=str,
+    )
+    parser.add_argument(
+        "--confidence_threshold",
+        default=0.3,
+        help="Confidence threshold for the model",
+        type=float,
+    )
+    parser.add_argument(
+        "--iou_threshold", default=0.7, help="IOU threshold for the model", type=float
+    )
+
+    args = parser.parse_args()
+    processor = VideoProcessor(
+        source_weights_path=args.source_weights_path,
+        source_video_path=args.source_video_path,
+        target_video_path=args.target_video_path,
+        confidence_threshold=args.confidence_threshold,
+        iou_threshold=args.iou_threshold,
+    )
+    processor.process_video()

mkdocs.yml

@@ -1,7 +1,7 @@
 site_name: Supervision
-site_url: https://roboflow.github.io/supervision
+site_url: https://supervision.roboflow.com/
 site_author: Roboflow
-site_description: A set of easy-to-use utils that will come in handy in any Computer Vision project
+site_description: A set of easy-to-use utilities that will come in handy in any computer vision project.
 repo_name: roboflow/supervision
 repo_url: https://github.com/roboflow/supervision
 edit_uri: https://github.com/roboflow/supervision/tree/main/docs
@@ -26,36 +26,43 @@ extra_css:
 
 nav:
   - Home: index.md
-  - Quickstart:
-    - Detections: quickstart/detections.md
-  - API reference:
+  - How to:
+      - Detect and Annotate: how_to/detect_and_annotate.md
+      - Process Video: how_to/process_video.md
+      - Track Objects: how_to/track_objects.md
+      - Filter Detections: how_to/filter_detections.md
+      - Evaluate Model: how_to/evaluate_model.md
+  - API:
     - Classifications:
         - Core: classification/core.md
     - Detections:
         - Core: detection/core.md
-        - Annotate: detection/annotate.md
         - Utils: detection/utils.md
-        - Tools:
-            - Polygon Zone: detection/tools/polygon_zone.md
-    - Trackers:
-        - Core: tracker/core.md
-    - Dataset:
-        - Core: dataset/core.md
+    - Tools:
+        - Line Zone: detection/tools/line_zone.md
+        - Polygon Zone: detection/tools/polygon_zone.md
+        - Inference Slicer: detection/tools/inference_slicer.md
+    - Annotators: annotators.md
+    - Trackers: trackers.md
+    - Datasets: datasets.md
     - Metrics:
-      - Detection Models: metrics/detection.md
+      - Object Detection: metrics/detection.md
     - Draw:
+        - Color: draw/color.md
         - Utils: draw/utils.md
     - Utils:
         - Video: utils/video.md
         - Image: utils/image.md
         - Notebook: utils/notebook.md
         - File: utils/file.md
+  - Assets: assets.md
   - Changelog: changelog.md
 
 theme:
   name: 'material'
-  logo: https://media.roboflow.com/open-source/supervision/supervision-lenny.png
-  favicon: https://media.roboflow.com/open-source/supervision/supervision-lenny.png
+  logo: assets/supervision-lenny.png
+  favicon: assets/supervision-lenny.png
+  custom_dir: docs/theme
   palette:
     # Palette for light mode
     - scheme: default
@@ -73,6 +80,8 @@ theme:
   font:
     text: Roboto
     code: Roboto Mono
+  features:
+    - content.code.copy
 
 plugins:
   - mkdocstrings
@@ -87,4 +96,8 @@ markdown_extensions:
   - pymdownx.tabbed:
       alternate_style: true
   - toc:
-      permalink: true
+      permalink: true
+
+extra_javascript:
+  - "https://widget.kapa.ai/kapa-widget.bundle.js"
+  - "javascript/init_kapa_widget.js"

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "supervision"
-version = "0.13.0"
+version = "0.18.0rc1"
 description = "A set of easy-to-use utils that will come in handy in any Computer Vision project"
 authors = ["Piotr Skalski <piotr.skalski92@gmail.com>"]
 maintainers = ["Piotr Skalski <piotr.skalski92@gmail.com>"]
@@ -10,17 +10,15 @@ packages = [{include = "supervision"}]
 homepage = "https://github.com/roboflow/supervision"
 repository = "https://github.com/roboflow/supervision"
 documentation = "https://github.com/roboflow/supervision/blob/main/README.md"
-keywords = ["machine-learning", "deep-learning", "vision", "ML", "DL", "AI", "YOLOv5", "YOLOv8", "Roboflow"]
+keywords = ["machine-learning", "deep-learning", "vision", "ML", "DL", "AI", "Roboflow"]
 
 classifiers=[
+    'Development Status :: 4 - Beta',
     'Intended Audience :: Developers',
+    'Intended Audience :: Education',
     'Intended Audience :: Science/Research',
     'License :: OSI Approved :: MIT License',
     'Programming Language :: Python :: 3',
-    'Programming Language :: Python :: 3.8',
-    'Programming Language :: Python :: 3.9',
-    'Programming Language :: Python :: 3.10',
-    'Programming Language :: Python :: 3.11',
     'Programming Language :: Python :: 3 :: Only',
     'Topic :: Software Development',
     'Topic :: Scientific/Engineering',
@@ -28,49 +26,161 @@ classifiers=[
     "Topic :: Scientific/Engineering :: Image Recognition",
     'Typing :: Typed',
     'Operating System :: Microsoft :: Windows',
-    'Operating System :: POSIX',
-    'Operating System :: Unix',
+    'Operating System :: POSIX :: Linux',
     'Operating System :: MacOS'
 ]
 
 [tool.poetry.dependencies]
-python = ">=3.8,<3.12.0"
-numpy = "^1.20.0"
-matplotlib = "^3.7.1"
-pyyaml = "^6.0"
-pillow = "^9.4.0"
-opencv-python = { version = "^4.8.0.74", optional = true }
-opencv-python-headless = "^4.8.0.74"
-scipy = "^1.9.0"
+python = "^3.8"
+numpy = ">=1.21.2"
+scipy =  ">=1.9.0"
+matplotlib = ">=3.5.0"
+pyyaml = ">=5.3"
+pillow = ">=9.4"
+opencv-python = { version = ">=4.5.5.64,<=4.8.1.78", optional = true }
+opencv-python-headless = ">=4.5.5.64,<=4.8.1.78"
+requests = { version = ">=2.26.0,<=2.31.0", optional = true }
+tqdm = { version = ">=4.62.3,<=4.66.1", optional = true }
+defusedxml = "^0.7.1"
 
 
 [tool.poetry.extras]
 desktop = ["opencv-python"]
-
+assets = ["requests","tqdm"]
 
 [tool.poetry.group.dev.dependencies]
 twine = "^4.0.2"
 pytest = "^7.2.2"
-wheel = "^0.40.0"
-notebook = "^6.5.3"
-build = "^0.10.0"
-ruff = "^0.0.280"
+wheel = ">=0.40,<0.43"
+notebook = ">=6.5.3,<8.0.0"
+build = ">=0.10,<1.1"
+ruff = ">=0.0.280,<0.1.12"
 isort = "^5.12.0"
-black = "^23.7.0"
 mypy = "^1.4.1"
 pre-commit = "^3.3.3"
-flake8 = { version = "*", python = ">=3.8.1,<3.12.0" }
+tox = "^4.11.4"
 
 
 [tool.poetry.group.docs.dependencies]
 mkdocs-material = "^9.1.4"
-mkdocstrings = {extras = ["python"], version = "^0.20.0"}
+mkdocstrings = {extras = ["python"], version = ">=0.20,<0.25"}
+
+
+[tool.isort]
+line_length = 88
+profile = "black"
+
+[tool.bandit]
+target = ["test", "supervision"]
+tests = ["B201", "B301", "B318", "B314", "B303", "B413", "B412", "B410"]
+
+[tool.autoflake]
+check = true
+imports = ["cv2", "supervision"]
+
+
+[tool.black]
+target-version = ["py38"]
+line-length = 88
+include = '\.pyi?$'
+exclude = '''
+/(
+    \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | _build
+  | buck-out
+  | build
+  | dist
+  | docs
+)/
+'''
+
+[tool.ruff]
+target-version = "py38"
+# Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default.
+select = ["E", "F"]
+ignore = []
+
+# Allow autofix for all enabled rules (when `--fix`) is provided.
+fixable = ["A", "B", "C", "D", "E", "F", "G", "I", "N", "Q", "S", "T", "W", "ANN", "ARG", "BLE", "COM", "DJ", "DTZ", "EM", "ERA", "EXE", "FBT", "ICN", "INP", "ISC", "NPY", "PD", "PGH", "PIE", "PL", "PT", "PTH", "PYI", "RET", "RSE", "RUF", "SIM", "SLF", "TCH", "TID", "TRY", "UP", "YTT"]
+unfixable = []
+
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+    "yarn-error.log",
+    "yarn.lock",
+    "docs",
+]
+
+# Same as Black.
+line-length = 88
+indent-width = 4
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.flake8-quotes]
+inline-quotes = "double"
+multiline-quotes = "double"
+docstring-quotes = "double"
+
+[tool.ruff.pydocstyle]
+convention = "google"
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["E402","F401"]
+"supervision/assets/list.py" = ["E501"]
+
+[tool.ruff.lint.mccabe]
+# Flag errors (`C901`) whenever the complexity level exceeds 5.
+max-complexity = 20
+
+
+[tool.ruff.pylint]
+max-args = 20
+
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"
 
 [tool.setuptools]
 include-package-data = false
 
 [tool.setuptools.packages.find]
-exclude = ["docs*", "test*"]
+exclude = ["docs*", "test*","examples*"]
 
 [build-system]
 requires = ["poetry-core"]

supervision/__init__.py

@@ -6,36 +6,67 @@ try:
 except importlib_metadata.PackageNotFoundError:
     __version__ = "development"
 
-
+from supervision.annotators.core import (
+    BlurAnnotator,
+    BoundingBoxAnnotator,
+    BoxCornerAnnotator,
+    CircleAnnotator,
+    ColorAnnotator,
+    DotAnnotator,
+    EllipseAnnotator,
+    HaloAnnotator,
+    HeatMapAnnotator,
+    LabelAnnotator,
+    MaskAnnotator,
+    PixelateAnnotator,
+    PolygonAnnotator,
+    TraceAnnotator,
+    TriangleAnnotator,
+)
+from supervision.annotators.utils import ColorLookup
 from supervision.classification.core import Classifications
 from supervision.dataset.core import (
     BaseDataset,
     ClassificationDataset,
     DetectionDataset,
 )
-from supervision.detection.annotate import BoxAnnotator, MaskAnnotator
+from supervision.detection.annotate import BoxAnnotator
 from supervision.detection.core import Detections
 from supervision.detection.line_counter import LineZone, LineZoneAnnotator
+from supervision.detection.tools.inference_slicer import InferenceSlicer
 from supervision.detection.tools.polygon_zone import PolygonZone, PolygonZoneAnnotator
 from supervision.detection.utils import (
     box_iou_batch,
+    calculate_masks_centroids,
     filter_polygons_by_area,
     mask_to_polygons,
     mask_to_xyxy,
+    move_boxes,
     non_max_suppression,
     polygon_to_mask,
     polygon_to_xyxy,
+    scale_boxes,
 )
 from supervision.draw.color import Color, ColorPalette
-from supervision.draw.utils import draw_filled_rectangle, draw_polygon, draw_text
+from supervision.draw.utils import (
+    calculate_dynamic_line_thickness,
+    calculate_dynamic_text_scale,
+    draw_filled_rectangle,
+    draw_image,
+    draw_line,
+    draw_polygon,
+    draw_rectangle,
+    draw_text,
+)
 from supervision.geometry.core import Point, Position, Rect
 from supervision.geometry.utils import get_polygon_center
 from supervision.metrics.detection import ConfusionMatrix, MeanAveragePrecision
 from supervision.tracker.byte_tracker.core import ByteTrack
 from supervision.utils.file import list_files_with_extensions
-from supervision.utils.image import ImageSink, crop
+from supervision.utils.image import ImageSink, crop_image
 from supervision.utils.notebook import plot_image, plot_images_grid
 from supervision.utils.video import (
+    FPSMonitor,
     VideoInfo,
     VideoSink,
     get_video_frames_generator,

supervision/annotators/base.py

@@ -0,0 +1,11 @@
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+from supervision.detection.core import Detections
+
+
+class BaseAnnotator(ABC):
+    @abstractmethod
+    def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
+        pass

supervision/annotators/utils.py

@@ -0,0 +1,121 @@
+from enum import Enum
+from typing import Optional, Union
+
+import numpy as np
+
+from supervision.detection.core import Detections
+from supervision.draw.color import Color, ColorPalette
+from supervision.geometry.core import Position
+
+
+class ColorLookup(Enum):
+    """
+    Enumeration class to define strategies for mapping colors to annotations.
+
+    This enum supports three different lookup strategies:
+        - `INDEX`: Colors are determined by the index of the detection within the scene.
+        - `CLASS`: Colors are determined by the class label of the detected object.
+        - `TRACK`: Colors are determined by the tracking identifier of the object.
+    """
+
+    INDEX = "index"
+    CLASS = "class"
+    TRACK = "track"
+
+    @classmethod
+    def list(cls):
+        return list(map(lambda c: c.value, cls))
+
+
+def resolve_color_idx(
+    detections: Detections,
+    detection_idx: int,
+    color_lookup: Union[ColorLookup, np.ndarray] = ColorLookup.CLASS,
+) -> int:
+    if detection_idx >= len(detections):
+        raise ValueError(
+            f"Detection index {detection_idx}"
+            f"is out of bounds for detections of length {len(detections)}"
+        )
+
+    if isinstance(color_lookup, np.ndarray):
+        if len(color_lookup) != len(detections):
+            raise ValueError(
+                f"Length of color lookup {len(color_lookup)}"
+                f"does not match length of detections {len(detections)}"
+            )
+        return color_lookup[detection_idx]
+    elif color_lookup == ColorLookup.INDEX:
+        return detection_idx
+    elif color_lookup == ColorLookup.CLASS:
+        if detections.class_id is None:
+            raise ValueError(
+                "Could not resolve color by class because"
+                "Detections do not have class_id"
+            )
+        return detections.class_id[detection_idx]
+    elif color_lookup == ColorLookup.TRACK:
+        if detections.tracker_id is None:
+            raise ValueError(
+                "Could not resolve color by track because"
+                "Detections do not have tracker_id"
+            )
+        return detections.tracker_id[detection_idx]
+
+
+def get_color_by_index(color: Union[Color, ColorPalette], idx: int) -> Color:
+    if isinstance(color, ColorPalette):
+        return color.by_idx(idx)
+    return color
+
+
+def resolve_color(
+    color: Union[Color, ColorPalette],
+    detections: Detections,
+    detection_idx: int,
+    color_lookup: Union[ColorLookup, np.ndarray] = ColorLookup.CLASS,
+) -> Color:
+    idx = resolve_color_idx(
+        detections=detections,
+        detection_idx=detection_idx,
+        color_lookup=color_lookup,
+    )
+    return get_color_by_index(color=color, idx=idx)
+
+
+class Trace:
+    def __init__(
+        self,
+        max_size: Optional[int] = None,
+        start_frame_id: int = 0,
+        anchor: Position = Position.CENTER,
+    ) -> None:
+        self.current_frame_id = start_frame_id
+        self.max_size = max_size
+        self.anchor = anchor
+
+        self.frame_id = np.array([], dtype=int)
+        self.xy = np.empty((0, 2), dtype=np.float32)
+        self.tracker_id = np.array([], dtype=int)
+
+    def put(self, detections: Detections) -> None:
+        frame_id = np.full(len(detections), self.current_frame_id, dtype=int)
+        self.frame_id = np.concatenate([self.frame_id, frame_id])
+        self.xy = np.concatenate(
+            [self.xy, detections.get_anchors_coordinates(self.anchor)]
+        )
+        self.tracker_id = np.concatenate([self.tracker_id, detections.tracker_id])
+
+        unique_frame_id = np.unique(self.frame_id)
+
+        if 0 < self.max_size < len(unique_frame_id):
+            max_allowed_frame_id = self.current_frame_id - self.max_size + 1
+            filtering_mask = self.frame_id >= max_allowed_frame_id
+            self.frame_id = self.frame_id[filtering_mask]
+            self.xy = self.xy[filtering_mask]
+            self.tracker_id = self.tracker_id[filtering_mask]
+
+        self.current_frame_id += 1
+
+    def get(self, tracker_id: int) -> np.ndarray:
+        return self.xy[self.tracker_id == tracker_id]

supervision/assets/__init__.py

@@ -0,0 +1,2 @@
+from supervision.assets.downloader import download_assets
+from supervision.assets.list import VideoAssets

supervision/assets/downloader.py

@@ -0,0 +1,95 @@
+import os
+from hashlib import new as hash_new
+from pathlib import Path
+from shutil import copyfileobj
+from typing import Union
+
+from supervision.assets.list import VIDEO_ASSETS, VideoAssets
+
+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"
+    )
+
+
+def is_md5_hash_matching(filename: str, original_md5_hash: str) -> bool:
+    """
+    Check if the MD5 hash of a file matches the original hash.
+
+    Parameters:
+        filename (str): The path to the file to be checked as a string.
+        original_md5_hash (str): The original MD5 hash to compare against.
+
+    Returns:
+        bool: True if the hashes match, False otherwise.
+    """
+    if not os.path.exists(filename):
+        return False
+
+    with open(filename, "rb") as file:
+        file_contents = file.read()
+        computed_md5_hash = hash_new(name="MD5")
+        computed_md5_hash.update(file_contents)
+
+    return computed_md5_hash.hexdigest() == original_md5_hash
+
+
+def download_assets(asset_name: Union[VideoAssets, str]) -> str:
+    """
+    Download a specified asset if it doesn't already exist or is corrupted.
+
+    Parameters:
+        asset_name (Union[VideoAssets, str]): The name or type of the asset to be
+            downloaded.
+
+    Returns:
+        str: The filename of the downloaded asset.
+
+    Example:
+        ```python
+        >>> from supervision.assets import download_assets, VideoAssets
+
+        >>> download_assets(VideoAssets.VEHICLES)
+        "vehicles.mp4"
+        ```
+    """
+
+    filename = asset_name.value if isinstance(asset_name, VideoAssets) else asset_name
+
+    if not Path(filename).exists() and filename in VIDEO_ASSETS:
+        print(f"Downloading {filename} assets \n")
+        response = get(VIDEO_ASSETS[filename][0], stream=True, allow_redirects=True)
+        response.raise_for_status()
+
+        file_size = int(response.headers.get("Content-Length", 0))
+        folder_path = Path(filename).expanduser().resolve()
+        folder_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with tqdm.wrapattr(
+            response.raw, "read", total=file_size, desc="", colour="#a351fb"
+        ) as raw_resp:
+            with folder_path.open("wb") as file:
+                copyfileobj(raw_resp, file)
+
+    elif Path(filename).exists():
+        if not is_md5_hash_matching(filename, VIDEO_ASSETS[filename][1]):
+            print("File corrupted. Re-downloading... \n")
+            os.remove(filename)
+            return download_assets(filename)
+
+        print(f"{filename} asset download complete. \n")
+
+    else:
+        valid_assets = ", ".join(asset.value for asset in VideoAssets)
+        raise ValueError(
+            f"Invalid asset. It should be one of the following: {valid_assets}."
+        )
+
+    return filename

supervision/assets/list.py

@@ -0,0 +1,65 @@
+from enum import Enum
+from typing import Dict, Tuple
+
+BASE_VIDEO_URL = "https://media.roboflow.com/supervision/video-examples/"
+
+
+class VideoAssets(Enum):
+    """
+    Each member of this enum represents a video asset. The value associated with each
+    member is the filename of the video.
+
+    | Enum Member            | Video Filename             | Video URL                                                                             |
+    |------------------------|----------------------------|---------------------------------------------------------------------------------------|
+    | `VEHICLES`             | `vehicles.mp4`             | [Link](https://media.roboflow.com/supervision/video-examples/vehicles.mp4)            |
+    | `MILK_BOTTLING_PLANT`  | `milk-bottling-plant.mp4`  | [Link](https://media.roboflow.com/supervision/video-examples/milk-bottling-plant.mp4) |
+    | `VEHICLES_2`           | `vehicles-2.mp4`           | [Link](https://media.roboflow.com/supervision/video-examples/vehicles-2.mp4)          |
+    | `GROCERY_STORE`        | `grocery-store.mp4`        | [Link](https://media.roboflow.com/supervision/video-examples/grocery-store.mp4)       |
+    | `SUBWAY`               | `subway.mp4`               | [Link](https://media.roboflow.com/supervision/video-examples/subway.mp4)              |
+    | `MARKET_SQUARE`        | `market-square.mp4`        | [Link](https://media.roboflow.com/supervision/video-examples/market-square.mp4)       |
+    | `PEOPLE_WALKING`       | `people-walking.mp4`       | [Link](https://media.roboflow.com/supervision/video-examples/people-walking.mp4)      |
+    """  # noqa: E501 // docs
+
+    VEHICLES = "vehicles.mp4"
+    MILK_BOTTLING_PLANT = "milk-bottling-plant.mp4"
+    VEHICLES_2 = "vehicles-2.mp4"
+    GROCERY_STORE = "grocery-store.mp4"
+    SUBWAY = "subway.mp4"
+    MARKET_SQUARE = "market-square.mp4"
+    PEOPLE_WALKING = "people-walking.mp4"
+
+    @classmethod
+    def list(cls):
+        return list(map(lambda c: c.value, cls))
+
+
+VIDEO_ASSETS: Dict[str, Tuple[str, str]] = {
+    VideoAssets.VEHICLES.value: (
+        f"{BASE_VIDEO_URL}{VideoAssets.VEHICLES.value}",
+        "8155ff4e4de08cfa25f39de96483f918",
+    ),
+    VideoAssets.VEHICLES_2.value: (
+        f"{BASE_VIDEO_URL}{VideoAssets.VEHICLES_2.value}",
+        "830af6fba21ffbf14867a7fea595937b",
+    ),
+    VideoAssets.MILK_BOTTLING_PLANT.value: (
+        f"{BASE_VIDEO_URL}{VideoAssets.MILK_BOTTLING_PLANT.value}",
+        "9e8fb6e883f842a38b3d34267290bdc7",
+    ),
+    VideoAssets.GROCERY_STORE.value: (
+        f"{BASE_VIDEO_URL}{VideoAssets.GROCERY_STORE.value}",
+        "11402e7b861c1980527d3d74cbe3b366",
+    ),
+    VideoAssets.SUBWAY.value: (
+        f"{BASE_VIDEO_URL}{VideoAssets.SUBWAY.value}",
+        "453475750691fb23c56a0cffef089194",
+    ),
+    VideoAssets.MARKET_SQUARE.value: (
+        f"{BASE_VIDEO_URL}{VideoAssets.MARKET_SQUARE.value}",
+        "859179bf4a21f80a8baabfdb2ed716dc",
+    ),
+    VideoAssets.PEOPLE_WALKING.value: (
+        f"{BASE_VIDEO_URL}{VideoAssets.PEOPLE_WALKING.value}",
+        "0574c053c8686c3f1dc0aa3743e45cb9",
+    ),
+}

supervision/classification/core.py

@@ -39,16 +39,61 @@ class Classifications:
         _validate_class_ids(self.class_id, n)
         _validate_confidence(self.confidence, n)
 
-    @classmethod
-    def from_yolov8(cls, yolov8_results) -> Classifications:
+    def __len__(self) -> int:
         """
-        Creates a Classifications instance from a [YOLOv8](https://github.com/ultralytics/ultralytics) inference result.
+        Returns the number of classifications.
+        """
+        return len(self.class_id)
+
+    @classmethod
+    def from_clip(cls, clip_results) -> Classifications:
+        """
+        Creates a Classifications instance from a
+        [clip](https://github.com/openai/clip) inference result.
 
         Args:
-            yolov8_results (ultralytics.yolo.engine.results.Results): The output Results instance from YOLOv8
+            clip_results (np.ndarray): The inference result from clip model.
 
         Returns:
-            Detections: A new Classifications object.
+            Classifications: A new Classifications object.
+
+        Example:
+            ```python
+            >>> from PIL import Image
+            >>> import clip
+            >>> import supervision as sv
+
+            >>> model, preprocess = clip.load('ViT-B/32')
+
+            >>> image = cv2.imread(SOURCE_IMAGE_PATH)
+            >>> image = preprocess(image).unsqueeze(0)
+
+            >>> text = clip.tokenize(["a diagram", "a dog", "a cat"])
+            >>> output, _ = model(image, text)
+            >>> classifications = sv.Classifications.from_clip(output)
+            ```
+        """
+
+        confidence = clip_results.softmax(dim=-1).cpu().detach().numpy()[0]
+
+        if len(confidence) == 0:
+            return cls(class_id=np.array([]), confidence=np.array([]))
+
+        class_ids = np.arange(len(confidence))
+        return cls(class_id=class_ids, confidence=confidence)
+
+    @classmethod
+    def from_ultralytics(cls, ultralytics_results) -> Classifications:
+        """
+        Creates a Classifications instance from a
+        [ultralytics](https://github.com/ultralytics/ultralytics) inference result.
+
+        Args:
+            ultralytics_results (ultralytics.engine.results.Results):
+                The inference result from ultralytics model.
+
+        Returns:
+            Classifications: A new Classifications object.
 
         Example:
             ```python
@@ -57,23 +102,69 @@ class Classifications:
             >>> import supervision as sv
 
             >>> image = cv2.imread(SOURCE_IMAGE_PATH)
-            >>> model = YOLO('yolov8s-cls.pt')
-            >>> result = model(image)[0]
-            >>> classifications = sv.Classifications.from_yolov8(result)
+            >>> model = YOLO('yolov8n-cls.pt')
+
+            >>> output = model(image)[0]
+            >>> classifications = sv.Classifications.from_ultralytics(output)
             ```
         """
-        confidence = yolov8_results.probs.data.cpu().numpy()
+        confidence = ultralytics_results.probs.data.cpu().numpy()
         return cls(class_id=np.arange(confidence.shape[0]), confidence=confidence)
 
+    @classmethod
+    def from_timm(cls, timm_results) -> Classifications:
+        """
+        Creates a Classifications instance from a
+        [timm](https://huggingface.co/docs/hub/timm) inference result.
+
+        Args:
+            timm_results: The inference result from timm model.
+
+        Returns:
+            Classifications: A new Classifications object.
+
+        Example:
+            ```python
+            >>> from PIL import Image
+            >>> import timm
+            >>> from timm.data import resolve_data_config, create_transform
+            >>> import supervision as sv
+
+            >>> model = timm.create_model(
+            ...     model_name='hf-hub:nateraw/resnet50-oxford-iiit-pet',
+            ...     pretrained=True
+            ... ).eval()
+
+            >>> config = resolve_data_config({}, model=model)
+            >>> transform = create_transform(**config)
+
+            >>> image = Image.open(SOURCE_IMAGE_PATH).convert('RGB')
+            >>> x = transform(image).unsqueeze(0)
+
+            >>> output = model(x)
+
+            >>> classifications = sv.Classifications.from_timm(output)
+            ```
+        """
+        confidence = timm_results.cpu().detach().numpy()[0]
+
+        if len(confidence) == 0:
+            return cls(class_id=np.array([]), confidence=np.array([]))
+
+        class_id = np.arange(len(confidence))
+        return cls(class_id=class_id, confidence=confidence)
+
     def get_top_k(self, k: int) -> Tuple[np.ndarray, np.ndarray]:
         """
-        Retrieve the top k class IDs and confidences, ordered in descending order by confidence.
+        Retrieve the top k class IDs and confidences,
+            ordered in descending order by confidence.
 
         Args:
             k (int): The number of top class IDs and confidences to retrieve.
 
         Returns:
-            Tuple[np.ndarray, np.ndarray]: A tuple containing the top k class IDs and confidences.
+            Tuple[np.ndarray, np.ndarray]: A tuple containing
+                the top k class IDs and confidences.
 
         Example:
             ```python

supervision/config.py

@@ -0,0 +1 @@
+CLASS_NAME_DATA_FIELD = "class_name"

supervision/dataset/core.py

@@ -54,7 +54,8 @@ class DetectionDataset(BaseDataset):
     Attributes:
         classes (List[str]): List containing dataset class names.
         images (Dict[str, np.ndarray]): Dictionary mapping image name to image.
-        annotations (Dict[str, Detections]): Dictionary mapping image name to annotations.
+        annotations (Dict[str, Detections]): Dictionary mapping
+            image name to annotations.
     """
 
     classes: List[str]
@@ -75,8 +76,9 @@ class DetectionDataset(BaseDataset):
         Iterate over the images and annotations in the dataset.
 
         Yields:
-            Iterator[Tuple[str, np.ndarray, Detections]]: An iterator that yields tuples containing the image name,
-                                                          the image data, and its corresponding annotation.
+            Iterator[Tuple[str, np.ndarray, Detections]]:
+                An iterator that yields tuples containing the image name,
+                the image data, and its corresponding annotation.
         """
         for image_name, image in self.images.items():
             yield image_name, image, self.annotations.get(image_name, None)
@@ -100,22 +102,27 @@ class DetectionDataset(BaseDataset):
         self, split_ratio=0.8, random_state=None, shuffle: bool = True
     ) -> Tuple[DetectionDataset, DetectionDataset]:
         """
-        Splits the dataset into two parts (training and testing) using the provided split_ratio.
+        Splits the dataset into two parts (training and testing)
+            using the provided split_ratio.
 
         Args:
-            split_ratio (float, optional): The ratio of the training set to the entire dataset.
-            random_state (int, optional): The seed for the random number generator. This is used for reproducibility.
+            split_ratio (float, optional): The ratio of the training
+                set to the entire dataset.
+            random_state (int, optional): The seed for the random number generator.
+                This is used for reproducibility.
             shuffle (bool, optional): Whether to shuffle the data before splitting.
 
         Returns:
-            Tuple[DetectionDataset, DetectionDataset]: A tuple containing the training and testing datasets.
+            Tuple[DetectionDataset, DetectionDataset]: A tuple containing
+                the training and testing datasets.
 
         Example:
             ```python
             >>> import supervision as sv
 
             >>> ds = sv.DetectionDataset(...)
-            >>> train_ds, test_ds = ds.split(split_ratio=0.7, random_state=42, shuffle=True)
+            >>> train_ds, test_ds = ds.split(split_ratio=0.7,
+            ...                              random_state=42, shuffle=True)
             >>> len(train_ds), len(test_ds)
             (700, 300)
             ```
@@ -150,37 +157,44 @@ class DetectionDataset(BaseDataset):
         approximation_percentage: float = 0.0,
     ) -> None:
         """
-        Exports the dataset to PASCAL VOC format. This method saves the images and their corresponding annotations in
-        PASCAL VOC format.
+        Exports the dataset to PASCAL VOC format. This method saves the images
+        and their corresponding annotations in PASCAL VOC format.
 
         Args:
-            images_directory_path (Optional[str]): The path to the directory where the images should be saved.
+            images_directory_path (Optional[str]): The path to the directory
+                where the images should be saved.
                 If not provided, images will not be saved.
-            annotations_directory_path (Optional[str]): The path to the directory where the annotations in
-                PASCAL VOC format should be saved. If not provided, annotations will not be saved.
-            min_image_area_percentage (float): The minimum percentage of detection area relative to
-                the image area for a detection to be included. Argument is used only for segmentation datasets.
-            max_image_area_percentage (float): The maximum percentage of detection area relative to
-                the image area for a detection to be included. Argument is used only for segmentation datasets.
-            approximation_percentage (float): The percentage of polygon points to be removed from the input polygon,
-            in the range [0, 1). Argument is used only for segmentation datasets.
+            annotations_directory_path (Optional[str]): The path to
+                the directory where the annotations in PASCAL VOC format should be
+                saved. If not provided, annotations will not be saved.
+            min_image_area_percentage (float): The minimum percentage of
+                detection area relative to
+                the image area for a detection to be included.
+                Argument is used only for segmentation datasets.
+            max_image_area_percentage (float): The maximum percentage
+                of detection area relative to
+                the image area for a detection to be included.
+                Argument is used only for segmentation datasets.
+            approximation_percentage (float): The percentage of
+                polygon points to be removed from the input polygon,
+                in the range [0, 1). Argument is used only for segmentation datasets.
         """
         if images_directory_path:
-            images_path = Path(images_directory_path)
-            images_path.mkdir(parents=True, exist_ok=True)
-
+            save_dataset_images(
+                images_directory_path=images_directory_path, images=self.images
+            )
         if annotations_directory_path:
-            annotations_path = Path(annotations_directory_path)
-            annotations_path.mkdir(parents=True, exist_ok=True)
+            Path(annotations_directory_path).mkdir(parents=True, exist_ok=True)
 
-        for image_name, image in self.images.items():
-            detections = self.annotations[image_name]
-
-            if images_directory_path:
-                cv2.imwrite(str(images_path / image_name), image)
+        for image_path, image in self.images.items():
+            detections = self.annotations[image_path]
 
             if annotations_directory_path:
-                annotation_name = Path(image_name).stem
+                annotation_name = Path(image_path).stem
+                annotations_path = os.path.join(
+                    annotations_directory_path, f"{annotation_name}.xml"
+                )
+                image_name = Path(image_path).name
                 pascal_voc_xml = detections_to_pascal_voc(
                     detections=detections,
                     classes=self.classes,
@@ -191,7 +205,7 @@ class DetectionDataset(BaseDataset):
                     approximation_percentage=approximation_percentage,
                 )
 
-                with open(annotations_path / f"{annotation_name}.xml", "w") as f:
+                with open(annotations_path, "w") as f:
                     f.write(pascal_voc_xml)
 
     @classmethod
@@ -205,12 +219,15 @@ class DetectionDataset(BaseDataset):
         Creates a Dataset instance from PASCAL VOC formatted data.
 
         Args:
-            images_directory_path (str): The path to the directory containing the images.
-            annotations_directory_path (str): The path to the directory containing the PASCAL VOC XML annotations.
-            force_masks (bool, optional): If True, forces masks to be loaded for all annotations, regardless of whether they are present.
+            images_directory_path (str): Path to the directory containing the images.
+            annotations_directory_path (str): Path to the directory
+                containing the PASCAL VOC XML annotations.
+            force_masks (bool, optional): If True, forces masks to
+                be loaded for all annotations, regardless of whether they are present.
 
         Returns:
-            DetectionDataset: A DetectionDataset instance containing the loaded images and annotations.
+            DetectionDataset: A DetectionDataset instance containing
+                the loaded images and annotations.
 
         Example:
             ```python
@@ -255,13 +272,19 @@ class DetectionDataset(BaseDataset):
         Creates a Dataset instance from YOLO formatted data.
 
         Args:
-            images_directory_path (str): The path to the directory containing the images.
-            annotations_directory_path (str): The path to the directory containing the YOLO annotation files.
-            data_yaml_path (str): The path to the data YAML file containing class information.
-            force_masks (bool, optional): If True, forces masks to be loaded for all annotations, regardless of whether they are present.
+            images_directory_path (str): The path to the
+                directory containing the images.
+            annotations_directory_path (str): The path to the directory
+                containing the YOLO annotation files.
+            data_yaml_path (str): The path to the data
+                YAML file containing class information.
+            force_masks (bool, optional): If True, forces
+                masks to be loaded for all annotations,
+                regardless of whether they are present.
 
         Returns:
-            DetectionDataset: A DetectionDataset instance containing the loaded images and annotations.
+            DetectionDataset: A DetectionDataset instance
+                containing the loaded images and annotations.
 
         Example:
             ```python
@@ -304,23 +327,32 @@ class DetectionDataset(BaseDataset):
         approximation_percentage: float = 0.0,
     ) -> None:
         """
-        Exports the dataset to YOLO format. This method saves the images and their corresponding
-        annotations in YOLO format.
+        Exports the dataset to YOLO format. This method saves the
+        images and their corresponding annotations in YOLO format.
 
         Args:
-            images_directory_path (Optional[str]): The path to the directory where the images should be saved.
+            images_directory_path (Optional[str]): The path to the
+                directory where the images should be saved.
                 If not provided, images will not be saved.
-            annotations_directory_path (Optional[str]): The path to the directory where the annotations in
-                YOLO format should be saved. If not provided, annotations will not be saved.
-            data_yaml_path (Optional[str]): The path where the data.yaml file should be saved.
+            annotations_directory_path (Optional[str]): The path to the
+                directory where the annotations in
+                YOLO format should be saved. If not provided,
+                annotations will not be saved.
+            data_yaml_path (Optional[str]): The path where the data.yaml
+                file should be saved.
                 If not provided, the file will not be saved.
-            min_image_area_percentage (float): The minimum percentage of detection area relative to
-                the image area for a detection to be included. Argument is used only for segmentation datasets.
-            max_image_area_percentage (float): The maximum percentage of detection area relative to
-                the image area for a detection to be included. Argument is used only for segmentation datasets.
-            approximation_percentage (float): The percentage of polygon points to be removed from the input polygon,
-                in the range [0, 1). This is useful for simplifying the annotations. Argument is used only for
-                segmentation datasets.
+            min_image_area_percentage (float): The minimum percentage of
+                detection area relative to
+                the image area for a detection to be included.
+                Argument is used only for segmentation datasets.
+            max_image_area_percentage (float): The maximum percentage
+                of detection area relative to
+                the image area for a detection to be included.
+                Argument is used only for segmentation datasets.
+            approximation_percentage (float): The percentage of polygon points to
+                be removed from the input polygon, in the range [0, 1).
+                This is useful for simplifying the annotations.
+                Argument is used only for segmentation datasets.
         """
         if images_directory_path is not None:
             save_dataset_images(
@@ -349,12 +381,16 @@ class DetectionDataset(BaseDataset):
         Creates a Dataset instance from COCO formatted data.
 
         Args:
-            images_directory_path (str): The path to the directory containing the images.
+            images_directory_path (str): The path to the
+                directory containing the images.
             annotations_path (str): The path to the json annotation files.
-            force_masks (bool, optional): If True, forces masks to be loaded for all annotations, regardless of whether they are present.
+            force_masks (bool, optional): If True,
+                forces masks to be loaded for all annotations,
+                regardless of whether they are present.
 
         Returns:
-            DetectionDataset: A DetectionDataset instance containing the loaded images and annotations.
+            DetectionDataset: A DetectionDataset instance containing
+                the loaded images and annotations.
 
         Example:
             ```python
@@ -394,20 +430,26 @@ class DetectionDataset(BaseDataset):
         approximation_percentage: float = 0.0,
     ) -> None:
         """
-        Exports the dataset to COCO format. This method saves the images and their corresponding
-        annotations in COCO format.
+        Exports the dataset to COCO format. This method saves the
+        images and their corresponding annotations in COCO format.
 
         Args:
-            images_directory_path (Optional[str]): The path to the directory where the images should be saved.
+            images_directory_path (Optional[str]): The path to the directory
+                where the images should be saved.
                 If not provided, images will not be saved.
             annotations_path (Optional[str]): The path to COCO annotation file.
-            min_image_area_percentage (float): The minimum percentage of detection area relative to
-                the image area for a detection to be included. Argument is used only for segmentation datasets.
-            max_image_area_percentage (float): The maximum percentage of detection area relative to
-                the image area for a detection to be included. Argument is used only for segmentation datasets.
-            approximation_percentage (float): The percentage of polygon points to be removed from the input polygon,
-                in the range [0, 1). This is useful for simplifying the annotations. Argument is used only for
-                segmentation datasets.
+            min_image_area_percentage (float): The minimum percentage of
+                detection area relative to
+                the image area for a detection to be included.
+                Argument is used only for segmentation datasets.
+            max_image_area_percentage (float): The maximum percentage of
+                detection area relative to
+                the image area for a detection to be included.
+                Argument is used only for segmentation datasets.
+            approximation_percentage (float): The percentage of polygon points
+                to be removed from the input polygon,
+                in the range [0, 1). This is useful for simplifying the annotations.
+                Argument is used only for segmentation datasets.
         """
         if images_directory_path is not None:
             save_dataset_images(
@@ -427,16 +469,20 @@ class DetectionDataset(BaseDataset):
     @classmethod
     def merge(cls, dataset_list: List[DetectionDataset]) -> DetectionDataset:
         """
-        Merge a list of `DetectionDataset` objects into a single `DetectionDataset` object.
+        Merge a list of `DetectionDataset` objects into a single
+            `DetectionDataset` object.
 
-        This method takes a list of `DetectionDataset` objects and combines their respective fields (`classes`, `images`,
+        This method takes a list of `DetectionDataset` objects and combines
+        their respective fields (`classes`, `images`,
         `annotations`) into a single `DetectionDataset` object.
 
         Args:
-            dataset_list (List[DetectionDataset]): A list of `DetectionDataset` objects to merge.
+            dataset_list (List[DetectionDataset]): A list of `DetectionDataset`
+                objects to merge.
 
         Returns:
-            (DetectionDataset): A single `DetectionDataset` object containing the merged data from the input list.
+            (DetectionDataset): A single `DetectionDataset` object containing
+            the merged data from the input list.
 
         Example:
             ```python
@@ -494,7 +540,8 @@ class ClassificationDataset(BaseDataset):
     Attributes:
         classes (List[str]): List containing dataset class names.
         images (Dict[str, np.ndarray]): Dictionary mapping image name to image.
-        annotations (Dict[str, Detections]): Dictionary mapping image name to annotations.
+        annotations (Dict[str, Detections]): Dictionary mapping
+            image name to annotations.
     """
 
     classes: List[str]
@@ -508,22 +555,27 @@ class ClassificationDataset(BaseDataset):
         self, split_ratio=0.8, random_state=None, shuffle: bool = True
     ) -> Tuple[ClassificationDataset, ClassificationDataset]:
         """
-        Splits the dataset into two parts (training and testing) using the provided split_ratio.
+        Splits the dataset into two parts (training and testing)
+            using the provided split_ratio.
 
         Args:
-            split_ratio (float, optional): The ratio of the training set to the entire dataset.
-            random_state (int, optional): The seed for the random number generator. This is used for reproducibility.
+            split_ratio (float, optional): The ratio of the training
+                set to the entire dataset.
+            random_state (int, optional): The seed for the
+                random number generator. This is used for reproducibility.
             shuffle (bool, optional): Whether to shuffle the data before splitting.
 
         Returns:
-            Tuple[ClassificationDataset, ClassificationDataset]: A tuple containing the training and testing datasets.
+            Tuple[ClassificationDataset, ClassificationDataset]: A tuple containing
+            the training and testing datasets.
 
         Example:
             ```python
             >>> import supervision as sv
 
             >>> cd = sv.ClassificationDataset(...)
-            >>> train_cd, test_cd = cd.split(split_ratio=0.7, random_state=42, shuffle=True)
+            >>> train_cd,test_cd = cd.split(split_ratio=0.7,
+            ...                             random_state=42,shuffle=True)
             >>> len(train_cd), len(test_cd)
             (700, 300)
             ```
@@ -553,16 +605,18 @@ class ClassificationDataset(BaseDataset):
         Saves the dataset as a multi-class folder structure.
 
         Args:
-            root_directory_path (str): The path to the directory where the dataset will be saved.
+            root_directory_path (str): The path to the directory
+                where the dataset will be saved.
         """
         os.makedirs(root_directory_path, exist_ok=True)
 
         for class_name in self.classes:
             os.makedirs(os.path.join(root_directory_path, class_name), exist_ok=True)
 
-        for image_name in self.images:
-            classification = self.annotations[image_name]
-            image = self.images[image_name]
+        for image_path in self.images:
+            classification = self.annotations[image_path]
+            image = self.images[image_path]
+            image_name = Path(image_path).name
             class_id = (
                 classification.class_id[0]
                 if classification.confidence is None
@@ -611,9 +665,9 @@ class ClassificationDataset(BaseDataset):
             class_id = classes.index(class_name)
 
             for image in os.listdir(os.path.join(root_directory_path, class_name)):
-                image_dir = os.path.join(root_directory_path, class_name, image)
-                images[image] = cv2.imread(image_dir)
-                annotations[image] = Classifications(
+                image_path = str(os.path.join(root_directory_path, class_name, image))
+                images[image_path] = cv2.imread(image_path)
+                annotations[image_path] = Classifications(
                     class_id=np.array([class_id]),
                 )
 

supervision/dataset/formats/coco.py

@@ -159,7 +159,7 @@ def load_coco_annotations(
         image_annotations = coco_annotations_groups.get(coco_image["id"], [])
         image_path = os.path.join(images_directory_path, image_name)
 
-        image = cv2.imread(str(image_path))
+        image = cv2.imread(image_path)
         annotation = coco_annotations_to_detections(
             image_annotations=image_annotations,
             resolution_wh=(image_width, image_height),
@@ -170,8 +170,8 @@ def load_coco_annotations(
             detections=annotation,
         )
 
-        images[image_name] = image
-        annotations[image_name] = annotation
+        images[image_path] = image
+        annotations[image_path] = annotation
 
     return classes, images, annotations
 
@@ -200,9 +200,9 @@ def save_coco_annotations(
     coco_categories = classes_to_coco_categories(classes=classes)
 
     image_id, annotation_id = 1, 1
-    for image_name, image in images.items():
+    for image_path, image in images.items():
         image_height, image_width, _ = image.shape
-
+        image_name = f"{Path(image_path).stem}{Path(image_path).suffix}"
         coco_image = {
             "id": image_id,
             "license": 1,
@@ -213,9 +213,9 @@ def save_coco_annotations(
         }
 
         coco_images.append(coco_image)
-        detections = annotations[image_name]
+        detections = annotations[image_path]
 
-        coco_annotation, label_id = detections_to_coco_annotations(
+        coco_annotation, annotation_id = detections_to_coco_annotations(
             detections=detections,
             image_id=image_id,
             annotation_id=annotation_id,

supervision/dataset/formats/pascal_voc.py

@@ -1,11 +1,11 @@
 import os
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
-from xml.dom.minidom import parseString
-from xml.etree.ElementTree import Element, SubElement, parse, tostring
+from xml.etree.ElementTree import Element, SubElement
 
 import cv2
 import numpy as np
+from defusedxml.ElementTree import fromstring, parse, tostring
 
 from supervision.dataset.utils import approximate_mask_with_polygons
 from supervision.detection.core import Detections
@@ -21,6 +21,9 @@ def object_to_pascal_voc(
     object_name = SubElement(root, "name")
     object_name.text = name
 
+    # https://github.com/roboflow/supervision/issues/144
+    xyxy += 1
+
     bndbox = SubElement(root, "bndbox")
     xmin = SubElement(bndbox, "xmin")
     xmin.text = str(int(xyxy[0]))
@@ -32,6 +35,8 @@ def object_to_pascal_voc(
     ymax.text = str(int(xyxy[3]))
 
     if polygon is not None:
+        # https://github.com/roboflow/supervision/issues/144
+        polygon += 1
         object_polygon = SubElement(root, "polygon")
         for index, point in enumerate(polygon, start=1):
             x_coordinate, y_coordinate = point
@@ -56,13 +61,19 @@ def detections_to_pascal_voc(
     Converts Detections object to Pascal VOC XML format.
 
     Args:
-        detections (Detections): A Detections object containing bounding boxes, class ids, and other relevant information.
-        classes (List[str]): A list of class names corresponding to the class ids in the Detections object.
+        detections (Detections): A Detections object containing bounding boxes,
+            class ids, and other relevant information.
+        classes (List[str]): A list of class names corresponding to the
+            class ids in the Detections object.
         filename (str): The name of the image file associated with the detections.
-        image_shape (Tuple[int, int, int]): The shape of the image file associated with the detections.
-        min_image_area_percentage (float): Minimum detection area relative to area of image associated with it.
-        max_image_area_percentage (float): Maximum detection area relative to area of image associated with it.
-        approximation_percentage (float): The percentage of polygon points to be removed from the input polygon, in the range [0, 1).
+        image_shape (Tuple[int, int, int]): The shape of the image
+            file associated with the detections.
+        min_image_area_percentage (float): Minimum detection area
+            relative to area of image associated with it.
+        max_image_area_percentage (float): Maximum detection area
+            relative to area of image associated with it.
+        approximation_percentage (float): The percentage of
+            polygon points to be removed from the input polygon, in the range [0, 1).
     Returns:
         str: An XML string in Pascal VOC format representing the detections.
     """
@@ -118,7 +129,7 @@ def detections_to_pascal_voc(
             annotation.append(next_object)
 
     # Generate XML string
-    xml_string = parseString(tostring(annotation)).toprettyxml(indent="  ")
+    xml_string = fromstring(tostring(annotation)).toprettyxml(indent="  ")
 
     return xml_string
 
@@ -129,15 +140,22 @@ def load_pascal_voc_annotations(
     force_masks: bool = False,
 ) -> Tuple[List[str], Dict[str, np.ndarray], Dict[str, Detections]]:
     """
-    Loads PASCAL VOC annotations and returns class names, images, and their corresponding detections.
+    Loads PASCAL VOC XML annotations and returns the image name,
+        a Detections instance, and a list of class names.
 
     Args:
         images_directory_path (str): The path to the directory containing the images.
-        annotations_directory_path (str): The path to the directory containing the PASCAL VOC annotation files.
-        force_masks (bool, optional): If True, forces masks to be loaded for all annotations, regardless of whether they are present.
+        annotations_directory_path (str): The path to the directory containing the
+            PASCAL VOC annotation files.
+        force_masks (bool, optional): If True, forces masks to be loaded for all
+            annotations, regardless of whether they are present.
 
     Returns:
-        Tuple[List[str], Dict[str, np.ndarray], Dict[str, Detections]]: A tuple containing a list of class names, a dictionary with image names as keys and images as values, and a dictionary with image names as keys and corresponding Detections instances as values.
+        Tuple[List[str], Dict[str, np.ndarray], Dict[str, Detections]]: A tuple
+            containing a list of class names,
+            a dictionary with image names as keys and
+            images as values, and a dictionary with image names as
+            keys and corresponding Detections instances as values.
     """
 
     image_paths = list_files_with_extensions(
@@ -150,12 +168,13 @@ def load_pascal_voc_annotations(
 
     for image_path in image_paths:
         image_name = Path(image_path).stem
-        image = cv2.imread(str(image_path))
+        image_path = str(image_path)
+        image = cv2.imread(image_path)
 
         annotation_path = os.path.join(annotations_directory_path, f"{image_name}.xml")
         if not os.path.exists(annotation_path):
-            images[image_path.name] = image
-            annotations[image_path.name] = Detections.empty()
+            images[image_path] = image
+            annotations[image_path] = Detections.empty()
             continue
 
         tree = parse(annotation_path)
@@ -166,8 +185,8 @@ def load_pascal_voc_annotations(
             root, classes, resolution_wh, force_masks
         )
 
-        images[image_path.name] = image
-        annotations[image_path.name] = annotation
+        images[image_path] = image
+        annotations[image_path] = annotation
 
     return classes, images, annotations
 
@@ -202,7 +221,9 @@ def detections_from_xml_obj(
     </annotation>
 
     Returns:
-        Tuple[Detections, List[str]]: A tuple containing a Detections object and an updated list of class names, extended with the class names from the XML object.
+        Tuple[Detections, List[str]]: A tuple containing a Detections object and an
+            updated list of class names, extended with the class names
+            from the XML object.
     """
     xyxy = []
     class_names = []
@@ -225,15 +246,21 @@ def detections_from_xml_obj(
         with_masks = force_masks if force_masks else with_masks
 
         for polygon in obj.findall("polygon"):
-            polygon_points = parse_polygon_points(polygon)
+            polygon = parse_polygon_points(polygon)
+            # https://github.com/roboflow/supervision/issues/144
+            polygon -= 1
 
             mask_from_polygon = polygon_to_mask(
-                polygon=np.array(polygon_points),
+                polygon=polygon,
                 resolution_wh=resolution_wh,
             )
             masks.append(mask_from_polygon)
 
     xyxy = np.array(xyxy) if len(xyxy) > 0 else np.empty((0, 4))
+
+    # https://github.com/roboflow/supervision/issues/144
+    xyxy -= 1
+
     for k in set(class_names):
         if k not in extended_classes:
             extended_classes.append(k)
@@ -241,20 +268,17 @@ def detections_from_xml_obj(
         [extended_classes.index(class_name) for class_name in class_names]
     )
 
-    if with_masks:
-        annotation = Detections(
-            xyxy=xyxy, mask=np.array(masks).astype(bool), class_id=class_id
-        )
-    else:
-        annotation = Detections(xyxy=xyxy, class_id=class_id)
+    annotation = Detections(
+        xyxy=xyxy.astype(np.float32),
+        mask=np.array(masks).astype(bool) if with_masks else None,
+        class_id=class_id,
+    )
+
     return annotation, extended_classes
 
 
-def parse_polygon_points(polygon: Element) -> List[List[int]]:
-    polygon_points = []
-    coords = polygon.findall(".//*")
-    for i in range(0, len(coords), 2):
-        x = int(coords[i].text)
-        y = int(coords[i + 1].text)
-        polygon_points.append([x, y])
-    return polygon_points
+def parse_polygon_points(polygon: Element) -> np.ndarray:
+    coordinates = [int(coord.text) for coord in polygon.findall(".//*")]
+    return np.array(
+        [(coordinates[i], coordinates[i + 1]) for i in range(0, len(coordinates), 2)]
+    )

supervision/dataset/formats/yolo.py

@@ -1,6 +1,6 @@
 import os
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple, Union
+from typing import Dict, List, Optional, Tuple
 
 import cv2
 import numpy as np
@@ -112,16 +112,23 @@ def load_yolo_annotations(
     force_masks: bool = False,
 ) -> Tuple[List[str], Dict[str, np.ndarray], Dict[str, Detections]]:
     """
-    Loads YOLO annotations and returns class names, images, and their corresponding detections.
+    Loads YOLO annotations and returns class names, images,
+        and their corresponding detections.
 
     Args:
         images_directory_path (str): The path to the directory containing the images.
-        annotations_directory_path (str): The path to the directory containing the YOLO annotation files.
-        data_yaml_path (str): The path to the data YAML file containing class information.
-        force_masks (bool, optional): If True, forces masks to be loaded for all annotations, regardless of whether they are present.
+        annotations_directory_path (str): The path to the directory
+            containing the YOLO annotation files.
+        data_yaml_path (str): The path to the data
+            YAML file containing class information.
+        force_masks (bool, optional): If True, forces masks to be loaded
+            for all annotations, regardless of whether they are present.
 
     Returns:
-        Tuple[List[str], Dict[str, np.ndarray], Dict[str, Detections]]: A tuple containing a list of class names, a dictionary with image names as keys and images as values, and a dictionary with image names as keys and corresponding Detections instances as values.
+        Tuple[List[str], Dict[str, np.ndarray], Dict[str, Detections]]:
+            A tuple containing a list of class names, a dictionary with
+            image names as keys and images as values, and a dictionary
+            with image names as keys and corresponding Detections instances as values.
     """
     image_paths = list_files_with_extensions(
         directory=images_directory_path, extensions=["jpg", "jpeg", "png"]
@@ -132,16 +139,17 @@ def load_yolo_annotations(
     annotations = {}
 
     for image_path in image_paths:
-        image_name = Path(image_path).stem
-        image = cv2.imread(str(image_path))
+        image_stem = Path(image_path).stem
+        image_path = str(image_path)
+        image = cv2.imread(image_path)
 
-        annotation_path = os.path.join(annotations_directory_path, f"{image_name}.txt")
+        annotation_path = os.path.join(annotations_directory_path, f"{image_stem}.txt")
         if not os.path.exists(annotation_path):
-            images[image_path.name] = image
-            annotations[image_path.name] = Detections.empty()
+            images[image_path] = image
+            annotations[image_path] = Detections.empty()
             continue
 
-        lines = read_txt_file(str(annotation_path))
+        lines = read_txt_file(file_path=annotation_path, skip_empty=True)
         h, w, _ = image.shape
         resolution_wh = (w, h)
 
@@ -151,8 +159,8 @@ def load_yolo_annotations(
             lines=lines, resolution_wh=resolution_wh, with_masks=with_masks
         )
 
-        images[image_path.name] = image
-        annotations[image_path.name] = annotation
+        images[image_path] = image
+        annotations[image_path] = annotation
     return classes, images, annotations
 
 
@@ -220,8 +228,9 @@ def save_yolo_annotations(
     approximation_percentage: float = 0.75,
 ) -> None:
     Path(annotations_directory_path).mkdir(parents=True, exist_ok=True)
-    for image_name, image in images.items():
-        detections = annotations[image_name]
+    for image_path, image in images.items():
+        detections = annotations[image_path]
+        image_name = Path(image_path).name
         yolo_annotations_name = _image_name_to_annotation_name(image_name=image_name)
         yolo_annotations_path = os.path.join(
             annotations_directory_path, yolo_annotations_name

supervision/dataset/utils.py

@@ -64,7 +64,7 @@ def build_class_index_mapping(
         if class_name not in target_classes:
             raise ValueError(
                 f"Class {class_name} not found in target classes. "
-                f"source_classes must be a subset of target_classes."
+                "source_classes must be a subset of target_classes."
             )
         corresponding_index = target_classes.index(class_name)
         index_mapping[i] = corresponding_index
@@ -97,7 +97,8 @@ def save_dataset_images(
 ) -> None:
     Path(images_directory_path).mkdir(parents=True, exist_ok=True)
 
-    for image_name, image in images.items():
+    for image_path, image in images.items():
+        image_name = Path(image_path).name
         target_image_path = os.path.join(images_directory_path, image_name)
         cv2.imwrite(target_image_path, image)
 

supervision/detection/annotate.py

@@ -12,12 +12,15 @@ class BoxAnnotator:
     A class for drawing bounding boxes on an image using detections provided.
 
     Attributes:
-        color (Union[Color, ColorPalette]): The color to draw the bounding box, can be a single color or a color palette
+        color (Union[Color, ColorPalette]): The color to draw the bounding box,
+            can be a single color or a color palette
         thickness (int): The thickness of the bounding box lines, default is 2
         text_color (Color): The color of the text on the bounding box, default is white
         text_scale (float): The scale of the text on the bounding box, default is 0.5
-        text_thickness (int): The thickness of the text on the bounding box, default is 1
-        text_padding (int): The padding around the text on the bounding box, default is 5
+        text_thickness (int): The thickness of the text on the bounding box,
+            default is 1
+        text_padding (int): The padding around the text on the bounding box,
+            default is 5
 
     """
 
@@ -49,8 +52,11 @@ class BoxAnnotator:
 
         Args:
             scene (np.ndarray): The image on which the bounding boxes will be drawn
-            detections (Detections): The detections for which the bounding boxes will be drawn
-            labels (Optional[List[str]]): An optional list of labels corresponding to each detection. If `labels` are not provided, corresponding `class_id` will be used as label.
+            detections (Detections): The detections for which the
+                bounding boxes will be drawn
+            labels (Optional[List[str]]): An optional list of labels
+                corresponding to each detection. If `labels` are not provided,
+                corresponding `class_id` will be used as label.
             skip_label (bool): Is set to `True`, skips bounding box label annotation.
         Returns:
             np.ndarray: The image with the bounding boxes drawn on it
@@ -138,58 +144,3 @@ class BoxAnnotator:
                 lineType=cv2.LINE_AA,
             )
         return scene
-
-
-class MaskAnnotator:
-    """
-    A class for overlaying masks on an image using detections provided.
-
-    Attributes:
-        color (Union[Color, ColorPalette]): The color to fill the mask, can be a single color or a color palette
-    """
-
-    def __init__(
-        self,
-        color: Union[Color, ColorPalette] = ColorPalette.default(),
-    ):
-        self.color: Union[Color, ColorPalette] = color
-
-    def annotate(
-        self, scene: np.ndarray, detections: Detections, opacity: float = 0.5
-    ) -> np.ndarray:
-        """
-        Overlays the masks on the given image based on the provided detections, with a specified opacity.
-
-        Args:
-            scene (np.ndarray): The image on which the masks will be overlaid
-            detections (Detections): The detections for which the masks will be overlaid
-            opacity (float): The opacity of the masks, between 0 and 1, default is 0.5
-
-        Returns:
-            np.ndarray: The image with the masks overlaid
-        """
-        if detections.mask is None:
-            return scene
-
-        for i in np.flip(np.argsort(detections.area)):
-            class_id = (
-                detections.class_id[i] if detections.class_id is not None else None
-            )
-            idx = class_id if class_id is not None else i
-            color = (
-                self.color.by_idx(idx)
-                if isinstance(self.color, ColorPalette)
-                else self.color
-            )
-
-            mask = detections.mask[i]
-            colored_mask = np.zeros_like(scene, dtype=np.uint8)
-            colored_mask[:] = color.as_bgr()
-
-            scene = np.where(
-                np.expand_dims(mask, axis=-1),
-                np.uint8(opacity * colored_mask + (1 - opacity) * scene),
-                scene,
-            )
-
-        return scene

supervision/detection/line_counter.py

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

supervision/detection/tools/inference_slicer.py

@@ -0,0 +1,180 @@
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Callable, Optional, Tuple
+
+import numpy as np
+
+from supervision.detection.core import Detections
+from supervision.detection.utils import move_boxes
+from supervision.utils.image import crop_image
+
+
+def move_detections(detections: Detections, offset: np.array) -> Detections:
+    """
+    Args:
+        detections (sv.Detections): Detections object to be moved.
+        offset (np.array): An array of shape `(2,)` containing offset values in format
+            is `[dx, dy]`.
+    Returns:
+        (sv.Detections) repositioned Detections object.
+    """
+    detections.xyxy = move_boxes(xyxy=detections.xyxy, offset=offset)
+    return detections
+
+
+class InferenceSlicer:
+    """
+    InferenceSlicer performs slicing-based inference for small target detection. This
+    method, often referred to as
+    [Slicing Adaptive Inference (SAHI)](https://ieeexplore.ieee.org/document/9897990),
+    involves dividing a larger image into smaller slices, performing inference on each
+    slice, and then merging the detections.
+
+    Args:
+        slice_wh (Tuple[int, int]): Dimensions of each slice in the format
+            `(width, height)`.
+        overlap_ratio_wh (Tuple[float, float]): Overlap ratio between consecutive
+            slices in the format `(width_ratio, height_ratio)`.
+        iou_threshold (Optional[float]): Intersection over Union (IoU) threshold
+            used for non-max suppression.
+        callback (Callable): A function that performs inference on a given image
+            slice and returns detections.
+        thread_workers (int): Number of threads for parallel execution.
+
+    Note:
+        The class ensures that slices do not exceed the boundaries of the original
+        image. As a result, the final slices in the row and column dimensions might be
+        smaller than the specified slice dimensions if the image's width or height is
+        not a multiple of the slice's width or height minus the overlap.
+    """
+
+    def __init__(
+        self,
+        callback: Callable[[np.ndarray], Detections],
+        slice_wh: Tuple[int, int] = (320, 320),
+        overlap_ratio_wh: Tuple[float, float] = (0.2, 0.2),
+        iou_threshold: Optional[float] = 0.5,
+        thread_workers: int = 1,
+    ):
+        self.slice_wh = slice_wh
+        self.overlap_ratio_wh = overlap_ratio_wh
+        self.iou_threshold = iou_threshold
+        self.callback = callback
+        self.thread_workers = thread_workers
+
+    def __call__(self, image: np.ndarray) -> Detections:
+        """
+        Performs slicing-based inference on the provided image using the specified
+            callback.
+
+        Args:
+            image (np.ndarray): The input image on which inference needs to be
+                performed. The image should be in the format
+                `(height, width, channels)`.
+
+        Returns:
+            Detections: A collection of detections for the entire image after merging
+                results from all slices and applying NMS.
+
+        Example:
+            ```python
+            >>> import cv2
+            >>> import supervision as sv
+            >>> from ultralytics import YOLO
+
+            >>> image = cv2.imread(SOURCE_IMAGE_PATH)
+            >>> model = YOLO(...)
+
+            >>> def callback(image_slice: np.ndarray) -> sv.Detections:
+            ...     result = model(image_slice)[0]
+            ...     return sv.Detections.from_ultralytics(result)
+
+            >>> slicer = sv.InferenceSlicer(callback = callback)
+
+            >>> detections = slicer(image)
+            ```
+        """
+        detections_list = []
+        resolution_wh = (image.shape[1], image.shape[0])
+        offsets = self._generate_offset(
+            resolution_wh=resolution_wh,
+            slice_wh=self.slice_wh,
+            overlap_ratio_wh=self.overlap_ratio_wh,
+        )
+
+        with ThreadPoolExecutor(max_workers=self.thread_workers) as executor:
+            futures = [
+                executor.submit(self._run_callback, image, offset) for offset in offsets
+            ]
+            for future in as_completed(futures):
+                detections_list.append(future.result())
+
+        return Detections.merge(detections_list=detections_list).with_nms(
+            threshold=self.iou_threshold
+        )
+
+    def _run_callback(self, image, offset) -> Detections:
+        """
+        Run the provided callback on a slice of an image.
+
+        Args:
+            image (np.ndarray): The input image on which inference needs to run
+            offset (np.ndarray): An array of shape `(4,)` containing coordinates
+                for the slice.
+
+        Returns:
+            Detections: A collection of detections for the slice.
+        """
+        image_slice = crop_image(image=image, xyxy=offset)
+        detections = self.callback(image_slice)
+        detections = move_detections(detections=detections, offset=offset[:2])
+
+        return detections
+
+    @staticmethod
+    def _generate_offset(
+        resolution_wh: Tuple[int, int],
+        slice_wh: Tuple[int, int],
+        overlap_ratio_wh: Tuple[float, float],
+    ) -> np.ndarray:
+        """
+        Generate offset coordinates for slicing an image based on the given resolution,
+        slice dimensions, and overlap ratios.
+
+        Args:
+            resolution_wh (Tuple[int, int]): A tuple representing the width and height
+                of the image to be sliced.
+            slice_wh (Tuple[int, int]): A tuple representing the desired width and
+                height of each slice.
+            overlap_ratio_wh (Tuple[float, float]): A tuple representing the desired
+                overlap ratio for width and height between consecutive slices. Each
+                value should be in the range [0, 1), where 0 means no overlap and a
+                value close to 1 means high overlap.
+
+        Returns:
+            np.ndarray: An array of shape `(n, 4)` containing coordinates for each
+                slice in the format `[xmin, ymin, xmax, ymax]`.
+
+        Note:
+            The function ensures that slices do not exceed the boundaries of the
+                original image. As a result, the final slices in the row and column
+                dimensions might be smaller than the specified slice dimensions if the
+                image's width or height is not a multiple of the slice's width or
+                height minus the overlap.
+        """
+        slice_width, slice_height = slice_wh
+        image_width, image_height = resolution_wh
+        overlap_ratio_width, overlap_ratio_height = overlap_ratio_wh
+
+        width_stride = slice_width - int(overlap_ratio_width * slice_width)
+        height_stride = slice_height - int(overlap_ratio_height * slice_height)
+
+        ws = np.arange(0, image_width, width_stride)
+        hs = np.arange(0, image_height, height_stride)
+
+        xmin, ymin = np.meshgrid(ws, hs)
+        xmax = np.clip(xmin + slice_width, 0, image_width)
+        ymax = np.clip(ymin + slice_height, 0, image_height)
+
+        offsets = np.stack([xmin, ymin, xmax, ymax], axis=-1).reshape(-1, 4)
+
+        return offsets

supervision/detection/tools/polygon_zone.py

@@ -17,9 +17,11 @@ class PolygonZone:
     A class for defining a polygon-shaped zone within a frame for detecting objects.
 
     Attributes:
-        polygon (np.ndarray): A polygon represented by a numpy array of shape `(N, 2)`, containing the `x`, `y` coordinates of the points.
+        polygon (np.ndarray): A polygon represented by a numpy array of shape
+            `(N, 2)`, containing the `x`, `y` coordinates of the points.
         frame_resolution_wh (Tuple[int, int]): The frame resolution (width, height)
-        triggering_position (Position): The position within the bounding box that triggers the zone (default: Position.BOTTOM_CENTER)
+        triggering_position (Position): The position within the bounding
+            box that triggers the zone (default: Position.BOTTOM_CENTER)
         current_count (int): The current count of detected objects within the zone
         mask (np.ndarray): The 2D bool mask for the polygon zone
     """
@@ -45,27 +47,30 @@ class PolygonZone:
         Determines if the detections are within the polygon zone.
 
         Parameters:
-            detections (Detections): The detections to be checked against the polygon zone
+            detections (Detections): The detections
+                to be checked against the polygon zone
 
         Returns:
-            np.ndarray: A boolean numpy array indicating if each detection is within the polygon zone
+            np.ndarray: A boolean numpy array indicating
+                if each detection is within the polygon zone
         """
 
         clipped_xyxy = clip_boxes(
-            boxes_xyxy=detections.xyxy, frame_resolution_wh=self.frame_resolution_wh
+            xyxy=detections.xyxy, resolution_wh=self.frame_resolution_wh
         )
         clipped_detections = replace(detections, xyxy=clipped_xyxy)
         clipped_anchors = np.ceil(
-            clipped_detections.get_anchor_coordinates(anchor=self.triggering_position)
+            clipped_detections.get_anchors_coordinates(anchor=self.triggering_position)
         ).astype(int)
         is_in_zone = self.mask[clipped_anchors[:, 1], clipped_anchors[:, 0]]
-        self.current_count = np.sum(is_in_zone)
+        self.current_count = int(np.sum(is_in_zone))
         return is_in_zone.astype(bool)
 
 
 class PolygonZoneAnnotator:
     """
-    A class for annotating a polygon-shaped zone within a frame with a count of detected objects.
+    A class for annotating a polygon-shaped zone within a
+        frame with a count of detected objects.
 
     Attributes:
         zone (PolygonZone): The polygon zone to be annotated
@@ -75,7 +80,8 @@ class PolygonZoneAnnotator:
         text_scale (float): The scale of the text on the polygon, default is 0.5
         text_thickness (int): The thickness of the text on the polygon, default is 1
         text_padding (int): The padding around the text on the polygon, default is 10
-        font (int): The font type for the text on the polygon, default is cv2.FONT_HERSHEY_SIMPLEX
+        font (int): The font type for the text on the polygon,
+            default is cv2.FONT_HERSHEY_SIMPLEX
         center (Tuple[int, int]): The center of the polygon for text placement
     """
 
@@ -105,7 +111,8 @@ class PolygonZoneAnnotator:
 
         Parameters:
             scene (np.ndarray): The image on which the polygon zone will be annotated
-            label (Optional[str]): An optional label for the count of detected objects within the polygon zone (default: None)
+            label (Optional[str]): An optional label for the count of detected objects
+                within the polygon zone (default: None)
 
         Returns:
             np.ndarray: The image with the polygon zone and count of detected objects

supervision/detection/utils.py

@@ -1,8 +1,11 @@
-from typing import List, Optional, Tuple
+from itertools import chain
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 import cv2
 import numpy as np
 
+from supervision.config import CLASS_NAME_DATA_FIELD
+
 MIN_POLYGON_POINT_COUNT = 3
 
 
@@ -10,29 +13,37 @@ def polygon_to_mask(polygon: np.ndarray, resolution_wh: Tuple[int, int]) -> np.n
     """Generate a mask from a polygon.
 
     Args:
-        polygon (np.ndarray): The polygon for which the mask should be generated, given as a list of vertices.
+        polygon (np.ndarray): The polygon for which the mask should be generated,
+            given as a list of vertices.
         resolution_wh (Tuple[int, int]): The width and height of the desired resolution.
 
     Returns:
-        np.ndarray: The generated 2D mask, where the polygon is marked with `1`'s and the rest is filled with `0`'s.
+        np.ndarray: The generated 2D mask, where the polygon is marked with
+            `1`'s and the rest is filled with `0`'s.
     """
     width, height = resolution_wh
     mask = np.zeros((height, width))
+
     cv2.fillPoly(mask, [polygon], color=1)
     return mask
 
 
 def box_iou_batch(boxes_true: np.ndarray, boxes_detection: np.ndarray) -> np.ndarray:
     """
-    Compute Intersection over Union (IoU) of two sets of bounding boxes - `boxes_true` and `boxes_detection`. Both sets
-    of boxes are expected to be in `(x_min, y_min, x_max, y_max)` format.
+    Compute Intersection over Union (IoU) of two sets of bounding boxes -
+        `boxes_true` and `boxes_detection`. Both sets
+        of boxes are expected to be in `(x_min, y_min, x_max, y_max)` format.
 
     Args:
-        boxes_true (np.ndarray): 2D `np.ndarray` representing ground-truth boxes. `shape = (N, 4)` where `N` is number of true objects.
-        boxes_detection (np.ndarray): 2D `np.ndarray` representing detection boxes. `shape = (M, 4)` where `M` is number of detected objects.
+        boxes_true (np.ndarray): 2D `np.ndarray` representing ground-truth boxes.
+            `shape = (N, 4)` where `N` is number of true objects.
+        boxes_detection (np.ndarray): 2D `np.ndarray` representing detection boxes.
+            `shape = (M, 4)` where `M` is number of detected objects.
 
     Returns:
-        np.ndarray: Pairwise IoU of boxes from `boxes_true` and `boxes_detection`. `shape = (N, M)` where `N` is number of true objects and `M` is number of detected objects.
+        np.ndarray: Pairwise IoU of boxes from `boxes_true` and `boxes_detection`.
+            `shape = (N, M)` where `N` is number of true objects and
+            `M` is number of detected objects.
     """
 
     def box_area(box):
@@ -55,17 +66,22 @@ def non_max_suppression(
     Perform Non-Maximum Suppression (NMS) on object detection predictions.
 
     Args:
-        predictions (np.ndarray): An array of object detection predictions in the format of `(x_min, y_min, x_max, y_max, score)` or `(x_min, y_min, x_max, y_max, score, class)`.
-        iou_threshold (float, optional): The intersection-over-union threshold to use for non-maximum suppression.
+        predictions (np.ndarray): An array of object detection predictions in
+            the format of `(x_min, y_min, x_max, y_max, score)`
+            or `(x_min, y_min, x_max, y_max, score, class)`.
+        iou_threshold (float, optional): The intersection-over-union threshold
+            to use for non-maximum suppression.
 
     Returns:
-        np.ndarray: A boolean array indicating which predictions to keep after non-maximum suppression.
+        np.ndarray: A boolean array indicating which predictions to keep after n
+            on-maximum suppression.
 
     Raises:
-        AssertionError: If `iou_threshold` is not within the closed range from `0` to `1`.
+        AssertionError: If `iou_threshold` is not within the
+            closed range from `0` to `1`.
     """
     assert 0 <= iou_threshold <= 1, (
-        f"Value of `iou_threshold` must be in the closed range from 0 to 1, "
+        "Value of `iou_threshold` must be in the closed range from 0 to 1, "
         f"{iou_threshold} given."
     )
     rows, columns = predictions.shape
@@ -89,31 +105,32 @@ def non_max_suppression(
         if not keep[index]:
             continue
 
-        # drop detections with iou > iou_threshold and same category as current detections
+        # drop detections with iou > iou_threshold and
+        # same category as current detections
         condition = (iou > iou_threshold) & (categories == category)
         keep = keep & ~condition
 
     return keep[sort_index.argsort()]
 
 
-def clip_boxes(
-    boxes_xyxy: np.ndarray, frame_resolution_wh: Tuple[int, int]
-) -> np.ndarray:
+def clip_boxes(xyxy: np.ndarray, resolution_wh: Tuple[int, int]) -> np.ndarray:
     """
     Clips bounding boxes coordinates to fit within the frame resolution.
 
     Args:
-        boxes_xyxy (np.ndarray): A numpy array of shape `(N, 4)` where each row corresponds to a bounding box in
+        xyxy (np.ndarray): A numpy array of shape `(N, 4)` where each
+            row corresponds to a bounding box in
         the format `(x_min, y_min, x_max, y_max)`.
-        frame_resolution_wh (Tuple[int, int]): A tuple of the form `(width, height)` representing the resolution of the
-        frame.
+        resolution_wh (Tuple[int, int]): A tuple of the form `(width, height)`
+            representing the resolution of the frame.
 
     Returns:
-        np.ndarray: A numpy array of shape `(N, 4)` where each row corresponds to a bounding box with coordinates
-        clipped to fit within the frame resolution.
+        np.ndarray: A numpy array of shape `(N, 4)` where each row
+            corresponds to a bounding box with coordinates clipped to fit
+            within the frame resolution.
     """
-    result = np.copy(boxes_xyxy)
-    width, height = frame_resolution_wh
+    result = np.copy(xyxy)
+    width, height = resolution_wh
     result[:, [0, 2]] = result[:, [0, 2]].clip(0, width)
     result[:, [1, 3]] = result[:, [1, 3]].clip(0, height)
     return result
@@ -131,10 +148,12 @@ def mask_to_xyxy(masks: np.ndarray) -> np.ndarray:
     Converts a 3D `np.array` of 2D bool masks into a 2D `np.array` of bounding boxes.
 
     Parameters:
-        masks (np.ndarray): A 3D `np.array` of shape `(N, W, H)` containing 2D bool masks
+        masks (np.ndarray): A 3D `np.array` of shape `(N, W, H)`
+            containing 2D bool masks
 
     Returns:
-        np.ndarray: A 2D `np.array` of shape `(N, 4)` containing the bounding boxes `(x_min, y_min, x_max, y_max)` for each mask
+        np.ndarray: A 2D `np.array` of shape `(N, 4)` containing the bounding boxes
+            `(x_min, y_min, x_max, y_max)` for each mask
     """
     n = masks.shape[0]
     bboxes = np.zeros((n, 4), dtype=int)
@@ -155,12 +174,14 @@ def mask_to_polygons(mask: np.ndarray) -> List[np.ndarray]:
     Converts a binary mask to a list of polygons.
 
     Parameters:
-        mask (np.ndarray): A binary mask represented as a 2D NumPy array of shape `(H, W)`,
-            where H and W are the height and width of the mask, respectively.
+        mask (np.ndarray): A binary mask represented as a 2D NumPy array of
+            shape `(H, W)`, where H and W are the height and width of
+            the mask, respectively.
 
     Returns:
-        List[np.ndarray]: A list of polygons, where each polygon is represented by a NumPy array of shape `(N, 2)`,
-            containing the `x`, `y` coordinates of the points. Polygons with fewer points than `MIN_POLYGON_POINT_COUNT = 3`
+        List[np.ndarray]: A list of polygons, where each polygon is represented by a
+            NumPy array of shape `(N, 2)`, containing the `x`, `y` coordinates
+            of the points. Polygons with fewer points than `MIN_POLYGON_POINT_COUNT = 3`
             are excluded from the output.
     """
 
@@ -183,15 +204,21 @@ def filter_polygons_by_area(
     Filters a list of polygons based on their area.
 
     Parameters:
-        polygons (List[np.ndarray]): A list of polygons, where each polygon is represented by a NumPy array of shape `(N, 2)`,
+        polygons (List[np.ndarray]): A list of polygons, where each polygon is
+            represented by a NumPy array of shape `(N, 2)`,
             containing the `x`, `y` coordinates of the points.
-        min_area (Optional[float]): The minimum area threshold. Only polygons with an area greater than or equal to this value
-            will be included in the output. If set to None, no minimum area constraint will be applied.
-        max_area (Optional[float]): The maximum area threshold. Only polygons with an area less than or equal to this value
-            will be included in the output. If set to None, no maximum area constraint will be applied.
+        min_area (Optional[float]): The minimum area threshold.
+            Only polygons with an area greater than or equal to this value
+            will be included in the output. If set to None,
+            no minimum area constraint will be applied.
+        max_area (Optional[float]): The maximum area threshold.
+            Only polygons with an area less than or equal to this value
+            will be included in the output. If set to None,
+            no maximum area constraint will be applied.
 
     Returns:
-        List[np.ndarray]: A new list of polygons containing only those with areas within the specified thresholds.
+        List[np.ndarray]: A new list of polygons containing only those with
+            areas within the specified thresholds.
     """
     if min_area is None and max_area is None:
         return polygons
@@ -213,7 +240,8 @@ def polygon_to_xyxy(polygon: np.ndarray) -> np.ndarray:
             containing the `x`, `y` coordinates of the points.
 
     Returns:
-        np.ndarray: A 1D NumPy array containing the bounding box `(x_min, y_min, x_max, y_max)` of the input polygon.
+        np.ndarray: A 1D NumPy array containing the bounding box
+            `(x_min, y_min, x_max, y_max)` of the input polygon.
     """
     x_min, y_min = np.min(polygon, axis=0)
     x_max, y_max = np.max(polygon, axis=0)
@@ -226,16 +254,23 @@ def approximate_polygon(
     """
     Approximates a given polygon by reducing a certain percentage of points.
 
-    This function uses the Ramer-Douglas-Peucker algorithm to simplify the input polygon by reducing the number of points
-    while preserving the general shape.
+    This function uses the Ramer-Douglas-Peucker algorithm to simplify the input
+        polygon by reducing the number of points
+        while preserving the general shape.
 
     Parameters:
-        polygon (np.ndarray): A 2D NumPy array of shape `(N, 2)` containing the `x`, `y` coordinates of the input polygon's points.
-        percentage (float): The percentage of points to be removed from the input polygon, in the range `[0, 1)`.
-        epsilon_step (float): Approximation accuracy step. Epsilon is the maximum distance between the original curve and its approximation.
+        polygon (np.ndarray): A 2D NumPy array of shape `(N, 2)` containing
+            the `x`, `y` coordinates of the input polygon's points.
+        percentage (float): The percentage of points to be removed from the
+            input polygon, in the range `[0, 1)`.
+        epsilon_step (float): Approximation accuracy step.
+            Epsilon is the maximum distance between the original curve
+            and its approximation.
 
     Returns:
-        np.ndarray: A new 2D NumPy array of shape `(M, 2)`, where `M <= N * (1 - percentage)`, containing the `x`, `y` coordinates of the
+        np.ndarray: A new 2D NumPy array of shape `(M, 2)`,
+            where `M <= N * (1 - percentage)`, containing
+            the `x`, `y` coordinates of the
             approximated polygon's points.
     """
 
@@ -267,7 +302,6 @@ def extract_ultralytics_masks(yolov8_results) -> Optional[np.ndarray]:
     orig_shape = yolov8_results.orig_shape
     inference_shape = tuple(yolov8_results.masks.data.shape[1:])
 
-    gain = 0
     pad = (0, 0)
 
     if inference_shape != orig_shape:
@@ -298,15 +332,31 @@ def extract_ultralytics_masks(yolov8_results) -> Optional[np.ndarray]:
 
 
 def process_roboflow_result(
-    roboflow_result: dict, class_list: List[str]
-) -> Tuple[np.ndarray, np.ndarray, np.ndarray, Optional[np.ndarray]]:
+    roboflow_result: dict,
+) -> Tuple[
+    np.ndarray,
+    np.ndarray,
+    np.ndarray,
+    Optional[np.ndarray],
+    Optional[np.ndarray],
+    Dict[str, List[np.ndarray]],
+]:
     if not roboflow_result["predictions"]:
-        return np.empty((0, 4)), np.empty(0), np.empty(0), None
+        return (
+            np.empty((0, 4)),
+            np.empty(0),
+            np.empty(0),
+            None,
+            None,
+            {CLASS_NAME_DATA_FIELD: np.empty(0)},
+        )
 
     xyxy = []
     confidence = []
     class_id = []
+    class_name = []
     masks = []
+    tracker_ids = []
 
     image_width = int(roboflow_result["image"]["width"])
     image_height = int(roboflow_result["image"]["height"])
@@ -321,23 +371,324 @@ def process_roboflow_result(
         x_max = x_min + width
         y_max = y_min + height
 
-        xyxy.append([x_min, y_min, x_max, y_max])
-        class_id.append(class_list.index(prediction["class"]))
-        confidence.append(prediction["confidence"])
-
         if "points" not in prediction:
-            continue
+            xyxy.append([x_min, y_min, x_max, y_max])
+            class_id.append(prediction["class_id"])
+            class_name.append(prediction["class"])
+            confidence.append(prediction["confidence"])
+            if "tracker_id" in prediction:
+                tracker_ids.append(prediction["tracker_id"])
+        elif len(prediction["points"]) >= 3:
+            polygon = np.array(
+                [[point["x"], point["y"]] for point in prediction["points"]], dtype=int
+            )
+            mask = polygon_to_mask(polygon, resolution_wh=(image_width, image_height))
+            xyxy.append([x_min, y_min, x_max, y_max])
+            class_id.append(prediction["class_id"])
+            class_name.append(prediction["class"])
+            confidence.append(prediction["confidence"])
+            masks.append(mask)
+            if "tracker_id" in prediction:
+                tracker_ids.append(prediction["tracker_id"])
 
-        polygon = np.array(
-            [[point["x"], point["y"]] for point in prediction["points"]], dtype=int
+    xyxy = np.array(xyxy) if len(xyxy) > 0 else np.empty((0, 4))
+    confidence = np.array(confidence) if len(confidence) > 0 else np.empty(0)
+    class_id = np.array(class_id).astype(int) if len(class_id) > 0 else np.empty(0)
+    class_name = np.array(class_name) if len(class_name) > 0 else np.empty(0)
+    masks = np.array(masks, dtype=bool) if len(masks) > 0 else None
+    tracker_id = np.array(tracker_ids).astype(int) if len(tracker_ids) > 0 else None
+    data = {CLASS_NAME_DATA_FIELD: class_name}
+
+    return xyxy, confidence, class_id, masks, tracker_id, data
+
+
+def move_boxes(xyxy: np.ndarray, offset: np.ndarray) -> np.ndarray:
+    """
+    Parameters:
+        xyxy (np.ndarray): An array of shape `(n, 4)` containing the bounding boxes
+            coordinates in format `[x1, y1, x2, y2]`
+        offset (np.array): An array of shape `(2,)` containing offset values in format
+            is `[dx, dy]`.
+
+    Returns:
+        np.ndarray: Repositioned bounding boxes.
+
+    Example:
+        ```python
+        >>> import numpy as np
+        >>> import supervision as sv
+
+        >>> boxes = np.array([[10, 10, 20, 20], [30, 30, 40, 40]])
+        >>> offset = np.array([5, 5])
+        >>> sv.move_boxes(boxes, offset)
+        ... array([
+        ...     [15, 15, 25, 25],
+        ...     [35, 35, 45, 45]
+        ... ])
+        ```
+    """
+    return xyxy + np.hstack([offset, offset])
+
+
+def scale_boxes(xyxy: np.ndarray, factor: float) -> np.ndarray:
+    """
+    Scale the dimensions of bounding boxes.
+
+    Parameters:
+        xyxy (np.ndarray): An array of shape `(n, 4)` containing the bounding boxes
+            coordinates in format `[x1, y1, x2, y2]`
+        factor (float): A float value representing the factor by which the box
+            dimensions are scaled. A factor greater than 1 enlarges the boxes, while a
+            factor less than 1 shrinks them.
+
+    Returns:
+        np.ndarray: Scaled bounding boxes.
+
+    Example:
+        ```python
+        >>> import numpy as np
+        >>> import supervision as sv
+
+        >>> boxes = np.array([[10, 10, 20, 20], [30, 30, 40, 40]])
+        >>> factor = 1.5
+        >>> sv.scale_boxes(boxes, factor)
+        ... array([
+        ...     [ 7.5,  7.5, 22.5, 22.5],
+        ...     [27.5, 27.5, 42.5, 42.5]
+        ... ])
+        ```
+    """
+    centers = (xyxy[:, :2] + xyxy[:, 2:]) / 2
+    new_sizes = (xyxy[:, 2:] - xyxy[:, :2]) * factor
+    return np.concatenate((centers - new_sizes / 2, centers + new_sizes / 2), axis=1)
+
+
+def calculate_masks_centroids(masks: np.ndarray) -> np.ndarray:
+    """
+    Calculate the centroids of binary masks in a tensor.
+
+    Parameters:
+        masks (np.ndarray): A 3D NumPy array of shape (num_masks, height, width).
+            Each 2D array in the tensor represents a binary mask.
+
+    Returns:
+        A 2D NumPy array of shape (num_masks, 2), where each row contains the x and y
+            coordinates (in that order) of the centroid of the corresponding mask.
+    """
+    num_masks, height, width = masks.shape
+    total_pixels = masks.sum(axis=(1, 2))
+
+    # offset for 1-based indexing
+    vertical_indices, horizontal_indices = np.indices((height, width)) + 0.5
+    # avoid division by zero for empty masks
+    total_pixels[total_pixels == 0] = 1
+
+    def sum_over_mask(indices: np.ndarray, axis: tuple) -> np.ndarray:
+        return np.tensordot(masks, indices, axes=axis)
+
+    aggregation_axis = ([1, 2], [0, 1])
+    centroid_x = sum_over_mask(horizontal_indices, aggregation_axis) / total_pixels
+    centroid_y = sum_over_mask(vertical_indices, aggregation_axis) / total_pixels
+
+    return np.column_stack((centroid_x, centroid_y)).astype(int)
+
+
+def validate_xyxy(xyxy: Any) -> None:
+    expected_shape = "(_, 4)"
+    actual_shape = str(getattr(xyxy, "shape", None))
+    is_valid = isinstance(xyxy, np.ndarray) and xyxy.ndim == 2 and xyxy.shape[1] == 4
+    if not is_valid:
+        raise ValueError(
+            f"xyxy must be a 2D np.ndarray with shape {expected_shape}, but got shape "
+            f"{actual_shape}"
         )
 
-        mask = polygon_to_mask(polygon, resolution_wh=(image_width, image_height))
-        masks.append(mask)
 
-    xyxy = np.array(xyxy)
-    confidence = np.array(confidence)
-    class_id = np.array(class_id).astype(int)
-    masks = np.array(masks, dtype=bool) if len(masks) > 0 else None
+def validate_mask(mask: Any, n: int) -> None:
+    expected_shape = f"({n}, H, W)"
+    actual_shape = str(getattr(mask, "shape", None))
+    is_valid = mask is None or (
+        isinstance(mask, np.ndarray) and len(mask.shape) == 3 and mask.shape[0] == n
+    )
+    if not is_valid:
+        raise ValueError(
+            f"mask must be a 3D np.ndarray with shape {expected_shape}, but got shape "
+            f"{actual_shape}"
+        )
 
-    return xyxy, confidence, class_id, masks
+
+def validate_class_id(class_id: Any, n: int) -> None:
+    expected_shape = f"({n},)"
+    actual_shape = str(getattr(class_id, "shape", None))
+    is_valid = class_id is None or (
+        isinstance(class_id, np.ndarray) and class_id.shape == (n,)
+    )
+    if not is_valid:
+        raise ValueError(
+            f"class_id must be a 1D np.ndarray with shape {expected_shape}, but got "
+            f"shape {actual_shape}"
+        )
+
+
+def validate_confidence(confidence: Any, n: int) -> None:
+    expected_shape = f"({n},)"
+    actual_shape = str(getattr(confidence, "shape", None))
+    is_valid = confidence is None or (
+        isinstance(confidence, np.ndarray) and confidence.shape == (n,)
+    )
+    if not is_valid:
+        raise ValueError(
+            f"confidence must be a 1D np.ndarray with shape {expected_shape}, but got "
+            f"shape {actual_shape}"
+        )
+
+
+def validate_tracker_id(tracker_id: Any, n: int) -> None:
+    expected_shape = f"({n},)"
+    actual_shape = str(getattr(tracker_id, "shape", None))
+    is_valid = tracker_id is None or (
+        isinstance(tracker_id, np.ndarray) and tracker_id.shape == (n,)
+    )
+    if not is_valid:
+        raise ValueError(
+            f"tracker_id must be a 1D np.ndarray with shape {expected_shape}, but got "
+            f"shape {actual_shape}"
+        )
+
+
+def validate_data(data: Dict[str, Any], n: int) -> None:
+    for key, value in data.items():
+        if isinstance(value, list):
+            if len(value) != n:
+                raise ValueError(f"Length of list for key '{key}' must be {n}")
+        elif isinstance(value, np.ndarray):
+            if value.ndim == 1 and value.shape[0] != n:
+                raise ValueError(f"Shape of np.ndarray for key '{key}' must be ({n},)")
+            elif value.ndim > 1 and value.shape[0] != n:
+                raise ValueError(
+                    f"First dimension of np.ndarray for key '{key}' must have size {n}"
+                )
+        else:
+            raise ValueError(f"Value for key '{key}' must be a list or np.ndarray")
+
+
+def validate_detections_fields(
+    xyxy: Any,
+    mask: Any,
+    class_id: Any,
+    confidence: Any,
+    tracker_id: Any,
+    data: Dict[str, Any],
+) -> None:
+    validate_xyxy(xyxy)
+    n = len(xyxy)
+    validate_mask(mask, n)
+    validate_class_id(class_id, n)
+    validate_confidence(confidence, n)
+    validate_tracker_id(tracker_id, n)
+    validate_data(data, n)
+
+
+def is_data_equal(data_a: Dict[str, np.ndarray], data_b: Dict[str, np.ndarray]) -> bool:
+    """
+    Compares the data payloads of two Detections instances.
+
+    Args:
+        data_a, data_b: The data payloads of the instances.
+
+    Returns:
+        True if the data payloads are equal, False otherwise.
+    """
+    return set(data_a.keys()) == set(data_b.keys()) and all(
+        np.array_equal(data_a[key], data_b[key]) for key in data_a
+    )
+
+
+def merge_data(
+    data_list: List[Dict[str, Union[np.ndarray, List]]],
+) -> Dict[str, Union[np.ndarray, List]]:
+    """
+    Merges the data payloads of a list of Detections instances.
+
+    Args:
+        data_list: The data payloads of the instances.
+
+    Returns:
+        A single data payload containing the merged data, preserving the original data
+            types (list or np.ndarray).
+
+    Raises:
+        ValueError: If data values within a single object have different lengths or if
+            dictionaries have different keys.
+    """
+    if not data_list:
+        return {}
+
+    all_keys_sets = [set(data.keys()) for data in data_list]
+    if not all(keys_set == all_keys_sets[0] for keys_set in all_keys_sets):
+        raise ValueError("All data dictionaries must have the same keys to merge.")
+
+    for data in data_list:
+        lengths = [len(value) for value in data.values()]
+        if len(set(lengths)) > 1:
+            raise ValueError(
+                "All data values within a single object must have equal length."
+            )
+
+    merged_data = {key: [] for key in all_keys_sets[0]}
+
+    for data in data_list:
+        for key in merged_data:
+            merged_data[key].append(data[key])
+
+    for key in merged_data:
+        if all(isinstance(item, list) for item in merged_data[key]):
+            merged_data[key] = list(chain.from_iterable(merged_data[key]))
+        elif all(isinstance(item, np.ndarray) for item in merged_data[key]):
+            ndim = merged_data[key][0].ndim
+            if ndim == 1:
+                merged_data[key] = np.hstack(merged_data[key])
+            elif ndim > 1:
+                merged_data[key] = np.vstack(merged_data[key])
+            else:
+                raise ValueError(f"Unexpected array dimension for key '{key}'.")
+        else:
+            raise ValueError(
+                f"Inconsistent data types for key '{key}'. Only np.ndarray and list "
+                f"types are allowed."
+            )
+
+    return merged_data
+
+
+def get_data_item(
+    data: Dict[str, Union[np.ndarray, List]],
+    index: Union[int, slice, List[int], np.ndarray],
+) -> Dict[str, Union[np.ndarray, List]]:
+    """
+    Retrieve a subset of the data dictionary based on the given index.
+
+    Args:
+        data: The data dictionary of the Detections object.
+        index: The index or indices specifying the subset to retrieve.
+
+    Returns:
+        A subset of the data dictionary corresponding to the specified index.
+    """
+    subset_data = {}
+    for key, value in data.items():
+        if isinstance(value, np.ndarray):
+            subset_data[key] = value[index]
+        elif isinstance(value, list):
+            if isinstance(index, slice):
+                subset_data[key] = value[index]
+            elif isinstance(index, (list, np.ndarray)):
+                subset_data[key] = [value[i] for i in index]
+            elif isinstance(index, int):
+                subset_data[key] = [value[index]]
+            else:
+                raise TypeError(f"Unsupported index type: {type(index)}")
+        else:
+            raise TypeError(f"Unsupported data type for key '{key}': {type(value)}")
+
+    return subset_data

supervision/draw/color.py

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

supervision/draw/utils.py

@@ -1,4 +1,5 @@
-from typing import Optional
+import os
+from typing import Optional, Tuple, Union
 
 import cv2
 import numpy as np
@@ -115,15 +116,19 @@ def draw_text(
     Draw text with background on a scene.
 
     Parameters:
-        scene (np.ndarray): A 2-dimensional numpy ndarray representing an image or scene.
+        scene (np.ndarray): A 2-dimensional numpy ndarray representing an image or scene
         text (str): The text to be drawn.
-        text_anchor (Point): The anchor point for the text, represented as a Point object with x and y attributes.
+        text_anchor (Point): The anchor point for the text, represented as a
+            Point object with x and y attributes.
         text_color (Color, optional): The color of the text. Defaults to black.
         text_scale (float, optional): The scale of the text. Defaults to 0.5.
         text_thickness (int, optional): The thickness of the text. Defaults to 1.
-        text_padding (int, optional): The amount of padding to add around the text when drawing a rectangle in the background. Defaults to 10.
-        text_font (int, optional): The font to use for the text. Defaults to cv2.FONT_HERSHEY_SIMPLEX.
-        background_color (Color, optional): The color of the background rectangle, if one is to be drawn. Defaults to None.
+        text_padding (int, optional): The amount of padding to add around the text
+            when drawing a rectangle in the background. Defaults to 10.
+        text_font (int, optional): The font to use for the text.
+            Defaults to cv2.FONT_HERSHEY_SIMPLEX.
+        background_color (Color, optional): The color of the background rectangle,
+            if one is to be drawn. Defaults to None.
 
     Returns:
         np.ndarray: The input scene with the text drawn on it.
@@ -132,7 +137,7 @@ def draw_text(
         ```python
         >>> scene = np.zeros((100, 100, 3), dtype=np.uint8)
         >>> text_anchor = Point(x=50, y=50)
-        >>> scene = draw_text(scene=scene, text="Hello, world!", text_anchor=text_anchor)
+        >>> scene = draw_text(scene=scene, text="Hello, world!",text_anchor=text_anchor)
         ```
     """
     text_width, text_height = cv2.getTextSize(
@@ -164,3 +169,103 @@ def draw_text(
         lineType=cv2.LINE_AA,
     )
     return scene
+
+
+def draw_image(
+    scene: np.ndarray, image: Union[str, np.ndarray], opacity: float, rect: Rect
+) -> np.ndarray:
+    """
+    Draws an image onto a given scene with specified opacity and dimensions.
+
+    Args:
+        scene (np.ndarray): Background image where the new image will be drawn.
+        image (Union[str, np.ndarray]): Image to draw.
+        opacity (float): Opacity of the image to be drawn.
+        rect (Rect): Rectangle specifying where to draw the image.
+
+    Returns:
+        np.ndarray: The updated scene.
+
+    Raises:
+        FileNotFoundError: If the image path does not exist.
+        ValueError: For invalid opacity or rectangle dimensions.
+    """
+
+    # Validate and load image
+    if isinstance(image, str):
+        if not os.path.exists(image):
+            raise FileNotFoundError(f"Image path ('{image}') does not exist.")
+        image = cv2.imread(image, cv2.IMREAD_UNCHANGED)
+
+    # Validate opacity
+    if not 0.0 <= opacity <= 1.0:
+        raise ValueError("Opacity must be between 0.0 and 1.0.")
+
+    # Validate rectangle dimensions
+    if (
+        rect.x < 0
+        or rect.y < 0
+        or rect.x + rect.width > scene.shape[1]
+        or rect.y + rect.height > scene.shape[0]
+    ):
+        raise ValueError("Invalid rectangle dimensions.")
+
+    # Resize and isolate alpha channel
+    image = cv2.resize(image, (rect.width, rect.height))
+    alpha_channel = (
+        image[:, :, 3]
+        if image.shape[2] == 4
+        else np.ones((rect.height, rect.width), dtype=image.dtype) * 255
+    )
+    alpha_scaled = cv2.convertScaleAbs(alpha_channel * opacity)
+
+    # Perform blending
+    scene_roi = scene[rect.y : rect.y + rect.height, rect.x : rect.x + rect.width]
+    alpha_float = alpha_scaled.astype(np.float32) / 255.0
+    blended_roi = cv2.convertScaleAbs(
+        (1 - alpha_float[..., np.newaxis]) * scene_roi
+        + alpha_float[..., np.newaxis] * image[:, :, :3]
+    )
+
+    # Update the scene
+    scene[rect.y : rect.y + rect.height, rect.x : rect.x + rect.width] = blended_roi
+
+    return scene
+
+
+def calculate_dynamic_text_scale(resolution_wh: Tuple[int, int]) -> float:
+    """
+    Calculate a dynamic font scale based on the resolution of an image.
+
+    Parameters:
+         resolution_wh (Tuple[int, int]): A tuple representing the width and height
+                 of the image.
+
+    Returns:
+         float: The calculated font scale factor.
+    """
+    return min(resolution_wh) * 1e-3
+
+
+def calculate_dynamic_line_thickness(resolution_wh: Tuple[int, int]) -> int:
+    """
+    Calculate a dynamic line thickness based on the resolution of an image.
+
+    Parameters:
+        resolution_wh (Tuple[int, int]): A tuple representing the width and height
+                of the image.
+
+    Returns:
+        int: The calculated line thickness in pixels.
+    """
+    min_dimension = min(resolution_wh)
+    if min_dimension < 480:
+        return 2
+    if min_dimension < 720:
+        return 2
+    if min_dimension < 1080:
+        return 2
+    if min_dimension < 2160:
+        return 4
+    else:
+        return 4