chore: update `mdformat` hook arguments to disable wrapping (#2307)

* chore: update `mdformat` hook arguments to disable wrapping
* fix(pre_commit): 🎨 auto format pre-commit hooks
* Apply suggestions from code review

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/CODE_OF_CONDUCT.md

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

.github/CONTRIBUTING.md

@@ -44,39 +44,12 @@ Before you contribute a new feature, consider submitting an Issue to discuss the
 
 ### API Design Principles
 
-Supervision APIs should remain generic, composable, and predictable across model
+Supervision APIs should remain generic, composable, and predictable across model families. Before adding a new integration, annotator option, or data conversion method, check the existing `sv.Detections`, `sv.KeyPoints`, and annotator patterns and follow these principles:
-families. Before adding a new integration, annotator option, or data conversion
-method, check the existing `sv.Detections`, `sv.KeyPoints`, and annotator
-patterns and follow these principles:
 
-1. **Model integrations normalize raw external outputs into existing Supervision
+1. **Model integrations normalize raw external outputs into existing Supervision containers.** Use `sv.Detections` for detection, segmentation, and other instance-level predictions that include boxes, masks, class ids, confidence scores, or extra per-instance fields. Use `sv.KeyPoints` for standalone keypoint or pose predictions when keypoints exist independently of detection boxes (e.g. pure pose estimation, landmark detection on pre-cropped images). Use `Detections.keypoints` when keypoints are always co-incident with boxes from the same model — the field stores an `(n, K, 2)` or `(n, K, 3)` array where the optional third channel is per-point confidence in `[0, 1]`.
-    containers.** Use `sv.Detections` for detection, segmentation, and other
+2. **Do not add a `from_<model>` method when the model already returns a Supervision object.** `from_*` methods are for converting raw outputs from external packages such as Ultralytics, Transformers, Inference, or MediaPipe. If a model's `predict()` method already returns `sv.Detections`, keep that result type and store additional structured payloads in `detections.data` or `detections.metadata` using documented keys.
-    instance-level predictions that include boxes, masks, class ids, confidence
+3. **Annotators render data; filtering and visibility are container state.** Filtering by confidence, class id, tracker id, geometry, or custom data should happen before annotation through the container slicing APIs, for example `detections[detections.confidence > 0.7]` or `key_points[key_points.confidence > 0.5]`. Per-point presentation state, such as a `KeyPoints.visible` mask, may live on the container and be honored consistently by annotators.
-    scores, or extra per-instance fields. Use `sv.KeyPoints` for standalone
+4. **Annotator constructor arguments should describe visual presentation, not model-quality gates.** Use constructor arguments for color, thickness, opacity, text, position, style, and generic visualization parameters such as sigma levels. Annotators may skip invalid geometry defensively, including missing points, zero-area boxes, non-finite coordinates, or points marked invisible on the container. They should not introduce confidence thresholds or model-specific quality gates as rendering options.
-    keypoint or pose predictions when keypoints exist independently of detection
-    boxes (e.g. pure pose estimation, landmark detection on pre-cropped images).
-    Use `Detections.keypoints` when keypoints are always co-incident with boxes
-    from the same model — the field stores an `(n, K, 2)` or `(n, K, 3)` array
-    where the optional third channel is per-point confidence in `[0, 1]`.
-2. **Do not add a `from_<model>` method when the model already returns a
-    Supervision object.** `from_*` methods are for converting raw outputs from
-    external packages such as Ultralytics, Transformers, Inference, or MediaPipe.
-    If a model's `predict()` method already returns `sv.Detections`, keep that
-    result type and store additional structured payloads in `detections.data` or
-    `detections.metadata` using documented keys.
-3. **Annotators render data; filtering and visibility are container state.**
-    Filtering by confidence, class id, tracker id, geometry, or custom data should
-    happen before annotation through the container slicing APIs, for example
-    `detections[detections.confidence > 0.7]` or `key_points[key_points.confidence > 0.5]`.
-    Per-point presentation state, such as a `KeyPoints.visible` mask, may
-    live on the container and be honored consistently by annotators.
-4. **Annotator constructor arguments should describe visual presentation, not
-    model-quality gates.** Use constructor arguments for color, thickness,
-    opacity, text, position, style, and generic visualization parameters such as
-    sigma levels. Annotators may skip invalid geometry defensively, including
-    missing points, zero-area boxes, non-finite coordinates, or points marked
-    invisible on the container. They should not introduce confidence thresholds or
-    model-specific quality gates as rendering options.
 
 ## How to Contribute Changes
 
@@ -263,18 +236,11 @@ To run the pre-commit tool, follow these steps:
 
 ### Docstrings
 
-All new functions and classes in `supervision` should include docstrings. This is a
+All new functions and classes in `supervision` should include docstrings. This is a prerequisite for any new functions and classes to be added to the library.
-prerequisite for any new functions and classes to be added to the library.
 
-`supervision` adheres to the
+`supervision` adheres to the [Google Python docstring style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods). Please refer to the style guide while writing docstrings for your contribution.
-[Google Python docstring style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods).
-Please refer to the style guide while writing docstrings for your contribution.
 
-Every docstring should include a usage example. When the example only uses
+Every docstring should include a usage example. When the example only uses `supervision`, NumPy, and the standard library — no optional extras, no external files or network access — strongly prefer `>>>` doctest format so it is automatically verified by the test suite. See [Doctests](#doctests) below for syntax guidance and for when fenced ```` ```python ```` blocks are appropriate instead.
-`supervision`, NumPy, and the standard library — no optional extras, no external files
-or network access — strongly prefer `>>>` doctest format so it is automatically
-verified by the test suite. See [Doctests](#doctests) below for syntax guidance and for
-when fenced ```` ```python ```` blocks are appropriate instead.
 
 ### Type checking
 
@@ -304,9 +270,7 @@ You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/)
 
 ## 🧑‍🍳 Cookbooks
 
-We are always looking for new examples and cookbooks to add to the `supervision`
+We are always looking for new examples and cookbooks to add to the `supervision` documentation. If you have a use case that you think would be helpful to others, please submit a PR with your example. Here are some guidelines for submitting a new example:
-documentation. If you have a use case that you think would be helpful to others, please
-submit a PR with your example. Here are some guidelines for submitting a new example:
 
 - Create a new notebook in the [`docs/notebooks`](https://github.com/roboflow/supervision/tree/develop/docs/notebooks) folder.
 - Add a link to the new notebook in [`docs/theme/cookbooks.html`](https://github.com/roboflow/supervision/blob/develop/docs/theme/cookbooks.html). Make sure to add the path to the new notebook, as well as a title, labels, author and supervision version.
@@ -334,11 +298,9 @@ uv run pytest --cov=supervision
 
 ### Test Structure
 
-Follow **Arrange-Act-Assert (AAA)**: one setup block, one action, one assertion group per
+Follow **Arrange-Act-Assert (AAA)**: one setup block, one action, one assertion group per test. Never put two independent actions in the same test.
-test. Never put two independent actions in the same test.
 
-**Class grouping:** Group related tests into a class. The class name carries the unit
+**Class grouping:** Group related tests into a class. The class name carries the unit under test; method names describe the expected outcome only — not the mechanism.
-under test; method names describe the expected outcome only — not the mechanism.
 
 ```python
 class TestDetectionsWithNms:
@@ -347,10 +309,7 @@ class TestDetectionsWithNms:
     def test_raises_when_confidence_missing(self): ...
 ```
 
-**Parametrize aggressively:** Three or more structurally identical tests should become a
+**Parametrize aggressively:** Three or more structurally identical tests should become a single `@pytest.mark.parametrize` case. Use `pytest.param(..., id="slug")` per case — not `ids=[...]` on the decorator — so the ID stays co-located with its arguments and survives reordering.
-single `@pytest.mark.parametrize` case. Use `pytest.param(..., id="slug")` per case —
-not `ids=[...]` on the decorator — so the ID stays co-located with its arguments and
-survives reordering.
 
 ```python
 @pytest.mark.parametrize(
@@ -367,23 +326,13 @@ def test_overlap_metric_determines_suppression(
     ...
 ```
 
-**Docstrings:** Every test function/method requires at minimum a one-line docstring
+**Docstrings:** Every test function/method requires at minimum a one-line docstring (within the project line length configured in `pyproject.toml`). Describe the scenario, not the implementation.
-(within the project line length configured in `pyproject.toml`). Describe the scenario,
-not the implementation.
 
 ### Doctests
 
-**Guidance:** when an example uses only `supervision`, NumPy, and the standard library
+**Guidance:** when an example uses only `supervision`, NumPy, and the standard library — no optional extras (e.g. no `--extra metrics` packages), no external files, no network, no devices — prefer `>>>` doctest format so it is automatically verified by the test suite. Fenced ```` ```python ```` blocks are appropriate when the example cannot reasonably be executed (e.g. loading a third-party model, reading a video file) or when the primary purpose is demonstrating error/exception behaviour rather than return values.
-— no optional extras (e.g. no `--extra metrics` packages), no external files, no
-network, no devices — prefer `>>>` doctest format so it is automatically verified by
-the test suite. Fenced ```` ```python ```` blocks are appropriate when the example
-cannot reasonably be executed (e.g. loading a third-party model, reading a video file)
-or when the primary purpose is demonstrating error/exception behaviour rather than
-return values.
 
-Doctests run automatically as part of the test suite via `--doctest-modules` in
+Doctests run automatically as part of the test suite via `--doctest-modules` in `pyproject.toml`. The `ELLIPSIS` and `NORMALIZE_WHITESPACE` flags are enabled globally, so `...` matches any output fragment and minor whitespace differences are ignored.
-`pyproject.toml`. The `ELLIPSIS` and `NORMALIZE_WHITESPACE` flags are enabled globally,
-so `...` matches any output fragment and minor whitespace differences are ignored.
 
 ```bash
 uv run pytest --doctest-modules src/
@@ -391,9 +340,7 @@ uv run pytest --doctest-modules src/
 
 **Writing a doctest**
 
-Use the `Example:` section of a Google-style docstring. Prefix each input line with
+Use the `Example:` section of a Google-style docstring. Prefix each input line with `>>>` and each continuation line with `...`. Place expected output immediately after the last input line with no blank line between them.
-`>>>` and each continuation line with `...`. Place expected output immediately after
-the last input line with no blank line between them.
 
 ```python
 def clip_boxes(xyxy: np.ndarray, resolution_wh: tuple) -> np.ndarray:
@@ -417,16 +364,12 @@ def clip_boxes(xyxy: np.ndarray, resolution_wh: tuple) -> np.ndarray:
 
 ### Key rules
 
-- **Single-line expression** — write the repr as expected output:
+- **Single-line expression** — write the repr as expected output: `>>> len(result)` → `1`
-    `>>> len(result)` → `1`
+- **Multi-line statement** — use `...` continuation: `>>> arr = np.array([` / `...     [1, 2],` / `... ])`
-- **Multi-line statement** — use `...` continuation:
-    `>>> arr = np.array([` / `...     [1, 2],` / `... ])`
 - **Print output** — write the printed string as expected output (no quotes).
 - **`None` return** — no output line needed (suppress with assignment or `_ =`).
 - **Large/variable arrays** — use `ELLIPSIS`: `array([...])` matches any content.
-- **`# doctest: +SKIP`** — use only as a last resort for genuinely non-runnable lines
+- **`# doctest: +SKIP`** — use only as a last resort for genuinely non-runnable lines (e.g. a GPU-only call inside an otherwise runnable example). Prefer splitting the example into two blocks instead.
-    (e.g. a GPU-only call inside an otherwise runnable example). Prefer splitting the
-    example into two blocks instead.
 
 Fenced ```` ```python ```` blocks remain appropriate for:
 

.github/copilot-instructions.md

@@ -141,6 +141,6 @@ Quick checklist:
 
 ## 🎯 Context-Aware Behavior
 
-**For general development tasks**: Follow [AGENTS.md](../AGENTS.md)
+- **For general development tasks**: Follow [AGENTS.md](../AGENTS.md)
-**For pull request reviews**: Follow [PR Review Guidelines](CONTRIBUTING.md#pr-review-guidelines)
+- **For pull request reviews**: Follow [PR Review Guidelines](CONTRIBUTING.md#pr-review-guidelines)
-**For detailed processes**: Consult [CONTRIBUTING.md](CONTRIBUTING.md)
+- **For detailed processes**: Consult [CONTRIBUTING.md](CONTRIBUTING.md)

.pre-commit-config.yaml

@@ -61,7 +61,7 @@ repos:
         additional_dependencies:
           - "mdformat-mkdocs[recommended]>=2.1.0"
           - "mdformat-ruff"
-        args: ["--number"]
+        args: ["--number", "--wrap=no"]
         exclude: ^(docs/changelog\.md|docs/deprecated\.md)$
 
   - repo: https://github.com/pre-commit/mirrors-mypy

AGENTS.md

@@ -1,10 +1,8 @@
 # Agent Guidelines for `supervision`
 
-These instructions define how AI agents (GitHub Copilot, Claude, etc.) should behave when
+These instructions define how AI agents (GitHub Copilot, Claude, etc.) should behave when assigned an issue, task, or multi-step problem in this repository.
-assigned an issue, task, or multi-step problem in this repository.
 
-Behave like a senior contributor: precise, efficient, aligned with the project's
+Behave like a senior contributor: precise, efficient, aligned with the project's philosophy, and focused on maintainability and clarity.
-philosophy, and focused on maintainability and clarity.
 
 ---
 
@@ -20,8 +18,7 @@ philosophy, and focused on maintainability and clarity.
 
 ## 2. Repository Conventions
 
-All work must follow the conventions of the `supervision` library
+All work must follow the conventions of the `supervision` library (see [CONTRIBUTING.md](.github/CONTRIBUTING.md) for full details).
-(see [CONTRIBUTING.md](.github/CONTRIBUTING.md) for full details).
 
 ### Branching & Commits
 
@@ -31,21 +28,13 @@ All work must follow the conventions of the `supervision` library
 
 ### Code Style
 
-- **Heading depth in docs/docstrings**: `###` maximum. `####` and deeper render
+- **Heading depth in docs/docstrings**: `###` maximum. `####` and deeper render identically to bold in mkdocs — use `**bold**` instead.
-    identically to bold in mkdocs — use `**bold**` instead.
 
-- **Formatting and linting** are enforced by **pre-commit**.
+- **Formatting and linting** are enforced by **pre-commit**. The hook chain typically includes: ruff-check, ruff-format, codespell, mdformat, prettier, pyproject-fmt, and standard pre-commit-hooks (trailing whitespace, YAML, TOML, etc.).
-    The hook chain typically includes: ruff-check, ruff-format, codespell, mdformat,
-    prettier, pyproject-fmt, and standard pre-commit-hooks (trailing whitespace, YAML, TOML, etc.).
 
-- **Type hints**: required on all new code. Type checking with mypy is encouraged but not
+- **Type hints**: required on all new code. Type checking with mypy is encouraged but not currently enforced systematically by pre-commit; see [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md) for the latest type-checking expectations.
-    currently enforced systematically by pre-commit; see [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md)
-    for the latest type-checking expectations.
 
-- **Docstrings**: Google Python docstring style. Required for all new functions and classes.
+- **Docstrings**: Google Python docstring style. Required for all new functions and classes. Every docstring should include a usage example. Prefer `>>>` doctest format when the example only uses `supervision`, NumPy, and stdlib (no optional extras, no external files or network). See §3a and CONTRIBUTING.md for syntax.
-    Every docstring should include a usage example. Prefer `>>>` doctest format when
-    the example only uses `supervision`, NumPy, and stdlib (no optional extras, no
-    external files or network). See §3a and CONTRIBUTING.md for syntax.
 
 ### API Consistency
 
@@ -76,17 +65,10 @@ All work must follow the conventions of the `supervision` library
 Full test guidelines are in [CONTRIBUTING.md](.github/CONTRIBUTING.md#tests). Key rules:
 
 - **AAA structure**: one arrange, one act, one assertion group per test. No second act.
-- **Class grouping**: group related tests into a class. Class name = unit under test.
+- **Class grouping**: group related tests into a class. Class name = unit under test. Method names describe the expected outcome only — not the mechanism.
-    Method names describe the expected outcome only — not the mechanism.
+- **Parametrize**: 3+ structurally identical tests → `@pytest.mark.parametrize`. Use `pytest.param(..., id="slug")` per case (not `ids=[...]` on the decorator).
-- **Parametrize**: 3+ structurally identical tests → `@pytest.mark.parametrize`.
+- **Docstrings**: every test function/method needs at minimum a one-line docstring within the project line length (see `pyproject.toml`). Describe the scenario, not the implementation.
-    Use `pytest.param(..., id="slug")` per case (not `ids=[...]` on the decorator).
+- **Doctests**: prefer `>>>` doctest when example uses only `supervision`, NumPy, and stdlib (no optional extras, no external files). Fenced ```` ```python ```` is fine when non-runnable (third-party model, video file, optional extra) or when the example's purpose is showing exception/error behaviour. See CONTRIBUTING.md §Doctests for syntax guide (continuation lines, ELLIPSIS, `+SKIP` rules).
-- **Docstrings**: every test function/method needs at minimum a one-line docstring
-    within the project line length (see `pyproject.toml`). Describe the scenario, not the implementation.
-- **Doctests**: prefer `>>>` doctest when example uses only `supervision`, NumPy, and
-    stdlib (no optional extras, no external files). Fenced ```` ```python ```` is fine
-    when non-runnable (third-party model, video file, optional extra) or when the
-    example's purpose is showing exception/error behaviour. See CONTRIBUTING.md
-    §Doctests for syntax guide (continuation lines, ELLIPSIS, `+SKIP` rules).
 
 ---
 
@@ -118,6 +100,5 @@ uv run pre-commit run --all-files
 ```
 
 - All pre-commit hooks must pass (formatting, linting, type checking, spell check, etc.).
-- All tests must pass before opening a PR. Note: some existing tests in the repo may
+- All tests must pass before opening a PR. Note: some existing tests in the repo may already be failing — your changes must not introduce new failures.
-    already be failing — your changes must not introduce new failures.
 - Fix any issues reported and re-run until clean.

LICENSE.md

@@ -2,20 +2,8 @@ MIT License
 
 Copyright (c) 2022 Roboflow
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

README.md

@@ -14,16 +14,9 @@
 
 <br>
 
-[![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
+[![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)](LICENSE.md) [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision) [![codecov](https://codecov.io/gh/roboflow/supervision/graph/badge.svg?token=HMNJ5FVZ36)](https://codecov.io/gh/roboflow/supervision)
-[![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision)
-[![license](https://img.shields.io/pypi/l/supervision)](LICENSE.md)
-[![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
-[![codecov](https://codecov.io/gh/roboflow/supervision/graph/badge.svg?token=HMNJ5FVZ36)](https://codecov.io/gh/roboflow/supervision)
 
-[![snyk](https://snyk.io/advisor/python/supervision/badge.svg)](https://snyk.io/advisor/python/supervision)
+[![snyk](https://snyk.io/advisor/python/supervision/badge.svg)](https://snyk.io/advisor/python/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?logo=discord&label=discord&labelColor=fff&color=5865f2&link=https%3A%2F%2Fdiscord.gg%2FGbfgXGJ8Bk)](https://discord.gg/GbfgXGJ8Bk)
-[![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?logo=discord&label=discord&labelColor=fff&color=5865f2&link=https%3A%2F%2Fdiscord.gg%2FGbfgXGJ8Bk)](https://discord.gg/GbfgXGJ8Bk)
 
 <div align="center">
     <a href="https://trendshift.io/repositories/124"  target="_blank"><img src="https://trendshift.io/api/badge/repositories/124" alt="roboflow%2Fsupervision | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
@@ -37,8 +30,7 @@
 
 ## 💻 install
 
-Pip install the supervision package in a
+Pip install the supervision package in a [**Python>=3.9**](https://www.python.org/) environment.
-[**Python>=3.9**](https://www.python.org/) environment.
 
 ```bash
 pip install supervision

docs/assets.md

@@ -5,8 +5,7 @@ description: API reference for supervision's assets module — download sample v
 
 # Assets
 
-Supervision offers an assets download utility that allows you to download image and video files
+Supervision offers an assets download utility that allows you to download image and video files that you can use in your demos.
-that you can use in your demos.
 
 <div class="md-typeset">
     <h2><a href="#supervision.assets.downloader.download_assets.download_assets">download_assets</a></h2>

docs/datasets/core.md

@@ -7,8 +7,7 @@ description: API reference for supervision's DetectionDataset and Classification
 
 !!! warning
 
-    Dataset API is still fluid and may change. If you use Dataset API in your project until further notice, freeze the
+    Dataset API is still fluid and may change. If you use Dataset API in your project until further notice, freeze the `supervision` version in your `requirements.txt` or `setup.py`.
-    `supervision` version in your `requirements.txt` or `setup.py`.
 
 <div class="md-typeset">
   <h2>DetectionDataset</h2>

docs/detection/annotators.md

@@ -196,13 +196,7 @@ Annotators accept detections and apply box or mask visualizations to the detecti
 
         !!! note
 
-            `MaskAnnotator` expects `detections.mask` to contain instance segmentation
+            `MaskAnnotator` expects `detections.mask` to contain instance segmentation masks aligned to the image passed to `annotate`. For dense masks, provide a boolean array of shape `(N, H, W)` where `(H, W)` matches the image height and width (it also accepts `sv.CompactMask`). If your model returns framework-specific results, convert them to `sv.Detections` first, for example with `sv.Detections.from_ultralytics(...)` or `sv.Detections.from_inference(...)`.
-            masks aligned to the image passed to `annotate`. For dense masks, provide a
-            boolean array of shape `(N, H, W)` where `(H, W)` matches the image height
-            and width (it also accepts `sv.CompactMask`). If your model returns
-            framework-specific results, convert them to `sv.Detections` first, for
-            example with `sv.Detections.from_ultralytics(...)` or
-            `sv.Detections.from_inference(...)`.
 
         <div class="result" markdown>
 

docs/detection/metrics.md

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

docs/how_to/benchmark_a_model.md

@@ -130,8 +130,7 @@ Evaluating your model requires careful selection of the dataset. Which images sh
 - **Validation Set**: This is the set of images used to validate the model during training. Every Nth training epoch, the model is evaluated on the validation set. Often the training is stopped once the validation loss stops improving. Therefore, even while the images aren't used to train the model, it still indirectly influences the training outcome.
 - **Test Set**: This is the set of images kept aside for model testing. It is exactly the set you should use for benchmarking. If the dataset was split correctly, none of these images would be shown to the model during training.
 
-Therefore, an unrelated dataset or the `test` set is the best choice for benchmarking.
+Therefore, an unrelated dataset or the `test` set is the best choice for benchmarking. Several other problems may arise:
-Several other problems may arise:
 
 - **Extra Classes**: An unrelated dataset may contain additional classes which you may need to [filter out](https://supervision.roboflow.com/how_to/filter_detections/#by-set-of-classes) before computing metrics.
 - **Class Mismatch**: In an unrelated dataset, the class names or IDs may be different to what your model produces, you'll need to remap them, which is [shown in this guide](#running-a-model).
@@ -145,8 +144,7 @@ At this stage, you should have:
 - A dataset of labeled images to evaluate the model.
 - A model prepared for benchmarking.
 
-With these ready, we can now run the model and obtain predictions.
+With these ready, we can now run the model and obtain predictions. We'll use `supervision` to create a dataset iterator, and then run the model on each image.
-We'll use `supervision` to create a dataset iterator, and then run the model on each image.
 
 === "Inference"
 
@@ -198,8 +196,7 @@ We'll use `supervision` to create a dataset iterator, and then run the model on
 
 ## Remapping classes
 
-Did you notice an issue in the above logic?
+Did you notice an issue in the above logic? Since we're using an unrelated dataset, the class names and IDs may be different from what the model was trained on.
-Since we're using an unrelated dataset, the class names and IDs may be different from what the model was trained on.
 
 We need to remap them to match the dataset classes. Here's how to do it:
 
@@ -259,8 +256,7 @@ Let's also remove the predictions that are not in the dataset classes.
 
     Dataset class names and IDs can be found in the `data.yaml` file, or by printing `dataset.classes`.
 
-    Each model will have a different class mapping, so make sure to check the model's documentation. In this case, the model was trained on the COCO dataset, with a class
+    Each model will have a different class mapping, so make sure to check the model's documentation. In this case, the model was trained on the COCO dataset, with a class configuration found [here](https://github.com/ultralytics/ultralytics/blob/main/ultralytics/cfg/datasets/coco8.yaml).
-    configuration found [here](https://github.com/ultralytics/ultralytics/blob/main/ultralytics/cfg/datasets/coco8.yaml).
 
     ```python
     import supervision as sv
@@ -293,8 +289,7 @@ Let's also remove the predictions that are not in the dataset classes.
 
 ## Visualizing Predictions
 
-The first step in evaluating your model’s performance is to visualize its predictions.
+The first step in evaluating your model’s performance is to visualize its predictions. This gives an intuitive sense of how well your model is detecting objects and where it might be failing.
-This gives an intuitive sense of how well your model is detecting objects and where it might be failing.
 
 ```python
 import supervision as sv

docs/how_to/detect_and_annotate.md

@@ -25,20 +25,13 @@ date_modified: 2026-04-22
     Then replace `<SOURCE_IMAGE_PATH>` with `"dog.jpeg"`.
     ```
 
-Supervision provides a seamless process for annotating predictions generated by various
+Supervision provides a seamless process for annotating predictions generated by various object detection and segmentation models. This guide shows how to perform inference with the [Inference](https://github.com/roboflow/inference), [Ultralytics](https://github.com/ultralytics/ultralytics) or [Transformers](https://github.com/huggingface/transformers) packages. Following this, you'll learn how to import these predictions into Supervision and use them to annotate source image.
-object detection and segmentation models. This guide shows how to perform inference
-with the [Inference](https://github.com/roboflow/inference),
-[Ultralytics](https://github.com/ultralytics/ultralytics) or
-[Transformers](https://github.com/huggingface/transformers) packages. Following this,
-you'll learn how to import these predictions into Supervision and use them to annotate
-source image.
 
 ![basic-annotation](https://media.roboflow.com/supervision_detect_and_annotate_example_1.png)
 
 ## Run Detection
 
-First, you'll need to obtain predictions from your object detection or segmentation
+First, you'll need to obtain predictions from your object detection or segmentation model.
-model.
 
 To run inference, initialize your chosen model and pass the source image to its predict or infer method. Supervision supports Roboflow Inference, Ultralytics YOLO, and Hugging Face Transformers -- select the tab matching your framework. The result is a framework-specific object you will convert to a `Detections` instance in the next step.
 
@@ -245,9 +238,7 @@ To draw bounding boxes and class labels on your image, create a `BoxAnnotator` a
 
 ## Display Custom Labels
 
-By default, [`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator)
+By default, [`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator) will label each detection with its `class_name` (if possible) or `class_id`. You can override this behavior by passing a list of custom `labels` to the `annotate` method.
-will label each detection with its `class_name` (if possible) or `class_id`. You can
-override this behavior by passing a list of custom `labels` to the `annotate` method.
 
 === "Inference"
 
@@ -347,11 +338,7 @@ override this behavior by passing a list of custom `labels` to the `annotate` me
 
 ## Annotate Image with Segmentations
 
-If you are running the segmentation model
+If you are running the segmentation model [`sv.MaskAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.MaskAnnotator) is a drop-in replacement for [`sv.BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) that will allow you to draw masks instead of boxes.
-[`sv.MaskAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.MaskAnnotator)
-is a drop-in replacement for
-[`sv.BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator)
-that will allow you to draw masks instead of boxes.
 
 === "Inference"
 

docs/how_to/detect_small_objects.md

@@ -10,11 +10,7 @@ date_modified: 2026-04-22
 
 # Detect Small Objects
 
-This guide shows how to detect small objects
+This guide shows how to detect small objects with the [Inference](https://github.com/roboflow/inference), [Ultralytics](https://github.com/ultralytics/ultralytics) or [Transformers](https://github.com/huggingface/transformers) packages using [`InferenceSlicer`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/#supervision.detection.tools.inference_slicer.InferenceSlicer).
-with the [Inference](https://github.com/roboflow/inference),
-[Ultralytics](https://github.com/ultralytics/ultralytics) or
-[Transformers](https://github.com/huggingface/transformers) packages using
-[`InferenceSlicer`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/#supervision.detection.tools.inference_slicer.InferenceSlicer).
 
 <video controls>
     <source src="https://media.roboflow.com/supervision_detect_small_objects_example.mp4" type="video/mp4">
@@ -22,8 +18,7 @@ with the [Inference](https://github.com/roboflow/inference),
 
 ## Baseline Detection
 
-Small object detection in high-resolution images presents challenges due to the objects'
+Small object detection in high-resolution images presents challenges due to the objects' size relative to the image resolution.
-size relative to the image resolution.
 
 Running a standard detection model on the full image establishes a baseline for comparison. Load your chosen model, pass the image through it, and convert the results into a `Detections` object. This baseline reveals how many small objects the model misses at native resolution, motivating the sliced inference approach shown later.
 
@@ -116,9 +111,7 @@ Running a standard detection model on the full image establishes a baseline for
 
 ## Input Resolution
 
-Modifying the input resolution of images before detection can enhance small object
+Modifying the input resolution of images before detection can enhance small object identification at the cost of processing speed and increased memory usage. This method is less effective for ultra-high-resolution images (4K and above).
-identification at the cost of processing speed and increased memory usage. This method
-is less effective for ultra-high-resolution images (4K and above).
 
 === "Inference"
 
@@ -166,9 +159,7 @@ is less effective for ultra-high-resolution images (4K and above).
 
 ## Inference Slicer
 
-[`InferenceSlicer`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/#supervision.detection.tools.inference_slicer.InferenceSlicer)
+[`InferenceSlicer`](https://supervision.roboflow.com/latest/detection/tools/inference_slicer/#supervision.detection.tools.inference_slicer.InferenceSlicer) processes high-resolution images by dividing them into smaller segments, detecting objects within each, and aggregating the results.
-processes high-resolution images by dividing them into smaller segments, detecting
-objects within each, and aggregating the results.
 
 <video controls>
     <source src="https://media.roboflow.com/supervision_detect_small_objects_example_2.mp4" type="video/mp4">

docs/how_to/filter_detections.md

@@ -10,11 +10,7 @@ date_modified: 2026-04-22
 
 # Filter Detections
 
-The advanced filtering capabilities of the `Detections` class offer users a versatile and efficient way to narrow down
+The advanced filtering capabilities of the `Detections` class offer users a versatile and efficient way to narrow down and refine object detections. This section outlines various filtering methods, including filtering by specific class or a set of classes, confidence, object area, bounding box area, relative area, box dimensions, and designated zones. Each method is demonstrated with concise code examples to provide users with a clear understanding of how to implement the filters in their applications.
-and refine object detections. This section outlines various filtering methods, including filtering by specific class
-or a set of classes, confidence, object area, bounding box area, relative area, box dimensions, and designated zones.
-Each method is demonstrated with concise code examples to provide users with a clear understanding of how to implement
-the filters in their applications.
 
 ### by specific class
 
@@ -124,8 +120,7 @@ Allows you to select detections with specific confidence value, for example high
 
 ### by area
 
-Allows you to select detections based on their size. We define the area as the number of pixels occupied by the
+Allows you to select detections based on their size. We define the area as the number of pixels occupied by the detection in the image. In the example below, we have sifted out the detections that are too small.
-detection in the image. In the example below, we have sifted out the detections that are too small.
 
 === "After"
 
@@ -159,10 +154,7 @@ detection in the image. In the example below, we have sifted out the detections
 
 ### by relative area
 
-Allows you to select detections based on their size in relation to the size of whole image. Sometimes the concept of
+Allows you to select detections based on their size in relation to the size of whole image. Sometimes the concept of detection size changes depending on the image. Detection occupying 10000 square px can be large on a 1280x720 image but small on a 3840x2160 image. In such cases, we can filter out detections based on the percentage of the image area occupied by them. In the example below, we remove too large detections.
-detection size changes depending on the image. Detection occupying 10000 square px can be large on a 1280x720 image
-but small on a 3840x2160 image. In such cases, we can filter out detections based on the percentage of the image area
-occupied by them. In the example below, we remove too large detections.
 
 === "After"
 
@@ -204,9 +196,7 @@ occupied by them. In the example below, we remove too large detections.
 
 ### by box dimensions
 
-Allows you to select detections based on their dimensions. The size of the bounding box, as well as its coordinates,
+Allows you to select detections based on their dimensions. The size of the bounding box, as well as its coordinates, can be criteria for rejecting detection. Implementing such filtering requires a bit of custom code but is relatively simple and fast.
-can be criteria for rejecting detection. Implementing such filtering requires a bit of custom code but is relatively
-simple and fast.
 
 === "After"
 
@@ -244,8 +234,7 @@ simple and fast.
 
 ### by `PolygonZone`
 
-Allows you to use `Detections` in combination with `PolygonZone` to weed out bounding boxes that are in and out of the
+Allows you to use `Detections` in combination with `PolygonZone` to weed out bounding boxes that are in and out of the zone. In the example below you can see how to filter out all detections located in the lower part of the image.
-zone. In the example below you can see how to filter out all detections located in the lower part of the image.
 
 === "After"
 

docs/how_to/process_datasets.md

@@ -8,27 +8,17 @@ authors:
 date_modified: 2026-04-22
 ---
 
-With Supervision, you can load and manipulate classification, object detection, and
+With Supervision, you can load and manipulate classification, object detection, and segmentation datasets. This tutorial will walk you through how to load, split, merge, visualize, and augment datasets in Supervision.
-segmentation datasets. This tutorial will walk you through how to load, split, merge,
-visualize, and augment datasets in Supervision.
 
 ## Download Dataset
 
-In this tutorial, we will use a dataset from
+In this tutorial, we will use a dataset from [Roboflow Universe](https://universe.roboflow.com/), a public repository of thousands of computer vision datasets. If you already have your dataset in [COCO](https://roboflow.com/formats/coco-json), [YOLO](https://roboflow.com/formats/yolov8-pytorch-txt), or [Pascal VOC](https://roboflow.com/formats/pascal-voc-xml) format, you can skip this section.
-[Roboflow Universe](https://universe.roboflow.com/), a public repository of
-thousands of computer vision datasets. If you already have your dataset in
-[COCO](https://roboflow.com/formats/coco-json),
-[YOLO](https://roboflow.com/formats/yolov8-pytorch-txt),
-or [Pascal VOC](https://roboflow.com/formats/pascal-voc-xml) format, you can skip this
-section.
 
 ```bash
 pip install roboflow
 ```
 
-Next, log into your Roboflow account and download the dataset of your choice in the
+Next, log into your Roboflow account and download the dataset of your choice in the COCO, YOLO, or Pascal VOC format. You can customize the following code snippet with your workspace ID, project ID, and version number.
-COCO, YOLO, or Pascal VOC format. You can customize the following code snippet with
-your workspace ID, project ID, and version number.
 
 === "COCO"
 
@@ -68,10 +58,7 @@ your workspace ID, project ID, and version number.
 
 ## Load Dataset
 
-The Supervision library provides convenient functions to load datasets in various
+The Supervision library provides convenient functions to load datasets in various formats. If your dataset is already split into train, test, and valid subsets, you can load each of those as separate [`sv.DetectionDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset) instances.
-formats. If your dataset is already split into train, test, and valid subsets, you can
-load each of those as separate [`sv.DetectionDataset`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset)
-instances.
 
 === "COCO"
 
@@ -159,9 +146,7 @@ instances.
 
 ## Split Dataset
 
-If your dataset is not already split into train, test, and valid subsets, you can
+If your dataset is not already split into train, test, and valid subsets, you can easily do so using the [`sv.DetectionDataset.split`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.split) method. We can split it as follows, ensuring a random shuffle of the data.
-easily do so using the [`sv.DetectionDataset.split`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.split)
-method. We can split it as follows, ensuring a random shuffle of the data.
 
 ```python
 import supervision as sv
@@ -180,9 +165,7 @@ len(ds_train), len(ds_valid), len(ds_test)
 
 ## Merge Dataset
 
-If you have multiple datasets that you would like to merge, you can do so using the
+If you have multiple datasets that you would like to merge, you can do so using the [`sv.DetectionDataset.merge`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.merge) method.
-[`sv.DetectionDataset.merge`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.merge)
-method.
 
 === "COCO"
 
@@ -288,10 +271,7 @@ method.
 
 ## Iterate over Dataset
 
-There are two ways to loop over a `sv.DetectionDataset`: using a direct
+There are two ways to loop over a `sv.DetectionDataset`: using a direct [for loop](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.__iter__) called on the `sv.DetectionDataset` instance or loading `sv.DetectionDataset` entries [by index](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.__getitem__).
-[for loop](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.__iter__)
-called on the `sv.DetectionDataset` instance or loading `sv.DetectionDataset` entries
-[by index](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.__getitem__).
 
 ```python
 import supervision as sv
@@ -310,13 +290,7 @@ for idx in range(len(ds)):
 
 ## Visualize Dataset
 
-The Supervision library provides tools for easily visualizing your detection dataset.
+The Supervision library provides tools for easily visualizing your detection dataset. You can create a grid of annotated images to quickly inspect your data and labels. First, initialize the [`sv.BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator) and [`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator). Then, iterate through a subset of the dataset (e.g., the first 25 images), drawing bounding boxes and class labels on each image. Finally, combine the annotated images into a grid for display.
-You can create a grid of annotated images to quickly inspect your data and labels.
-First, initialize the [`sv.BoxAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.BoxAnnotator)
-and [`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator).
-Then, iterate through a subset of the dataset (e.g., the first 25 images), drawing
-bounding boxes and class labels on each image. Finally, combine the annotated images
-into a grid for display.
 
 ```python
 import supervision as sv
@@ -395,22 +369,13 @@ sv.plot_images_grid(
 
 ## Augment Dataset
 
-In this section, we'll explore using Supervision in combination with Albumentations to
+In this section, we'll explore using Supervision in combination with Albumentations to augment our dataset. Data augmentation is a common technique in computer vision to increase the size and diversity of training datasets, leading to improved model performance and generalization.
-augment our dataset. Data augmentation is a common technique in computer vision to
-increase the size and diversity of training datasets, leading to improved model
-performance and generalization.
 
 ```bash
 pip install albumentations
 ```
 
-Albumentations provides a flexible and powerful API for image augmentation. The core of
+Albumentations provides a flexible and powerful API for image augmentation. The core of the library is the [`Compose`](https://albumentations.ai/docs/api-reference/albumentations/core/composition/#Compose) class, which allows you to chain multiple image transformations together. Each transformation is defined using a dedicated class, such as [`HorizontalFlip`](https://albumentations.ai/docs/api-reference/albumentations/augmentations/geometric/flip/#HorizontalFlip), [`RandomBrightnessContrast`](https://albumentations.ai/docs/api-reference/albumentations/augmentations/pixel/transforms/#RandomBrightnessContrast), or [`Perspective`](https://albumentations.ai/docs/api-reference/albumentations/augmentations/geometric/transforms/#Perspective).
-the library is the [`Compose`](https://albumentations.ai/docs/api-reference/albumentations/core/composition/#Compose)
-class, which allows you to chain multiple image transformations together. Each
-transformation is defined using a dedicated class, such as
-[`HorizontalFlip`](https://albumentations.ai/docs/api-reference/albumentations/augmentations/geometric/flip/#HorizontalFlip),
-[`RandomBrightnessContrast`](https://albumentations.ai/docs/api-reference/albumentations/augmentations/pixel/transforms/#RandomBrightnessContrast),
-or [`Perspective`](https://albumentations.ai/docs/api-reference/albumentations/augmentations/geometric/transforms/#Perspective).
 
 ```python
 import albumentations as A
@@ -428,8 +393,7 @@ augmentation = A.Compose(
 )
 ```
 
-The key is to set `format='pascal_voc'`, which corresponds to the
+The key is to set `format='pascal_voc'`, which corresponds to the `[x_min, y_min, x_max, y_max]` bounding box format used in Supervision.
-`[x_min, y_min, x_max, y_max]` bounding box format used in Supervision.
 
 ```python
 import numpy as np

docs/how_to/save_detections.md

@@ -10,19 +10,11 @@ date_modified: 2026-04-22
 
 # Save Detections
 
-Supervision enables an easy way to save detections in .CSV and .JSON files for offline
+Supervision enables an easy way to save detections in .CSV and .JSON files for offline processing. This guide demonstrates how to perform video inference using the [Inference](https://github.com/roboflow/inference), [Ultralytics](https://github.com/ultralytics/ultralytics) or [Transformers](https://github.com/huggingface/transformers) packages and save their results with [`sv.CSVSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink) and [`sv.JSONSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.json_sink.JSONSink).
-processing. This guide demonstrates how to perform video inference using the
-[Inference](https://github.com/roboflow/inference),
-[Ultralytics](https://github.com/ultralytics/ultralytics) or
-[Transformers](https://github.com/huggingface/transformers) packages and save their results with
-[`sv.CSVSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink) and
-[`sv.JSONSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.json_sink.JSONSink).
 
 ## Run Detection
 
-First, you'll need to obtain predictions from your object detection or segmentation
+First, you'll need to obtain predictions from your object detection or segmentation model. You can learn more on this topic in our [How to Detect and Annotate](https://supervision.roboflow.com/latest/how_to/detect_and_annotate/) guide.
-model. You can learn more on this topic in our
-[How to Detect and Annotate](https://supervision.roboflow.com/latest/how_to/detect_and_annotate/) guide.
 
 To generate predictions for saving, initialize your model and iterate over video frames using `sv.get_video_frames_generator`. Each frame is passed to the model, and the raw output is converted into a `sv.Detections` object. This detection loop forms the foundation for both CSV and JSON export workflows shown below.
 
@@ -82,11 +74,7 @@ To generate predictions for saving, initialize your model and iterate over video
 
 ## Save Detections as CSV
 
-To save detections to a `.CSV` file, open our
+To save detections to a `.CSV` file, open our [`sv.CSVSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink) and then pass the [`sv.Detections`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections) object resulting from the inference to it. Its fields are parsed and saved on disk.
-[`sv.CSVSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink)
-and then pass the
-[`sv.Detections`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections)
-object resulting from the inference to it. Its fields are parsed and saved on disk.
 
 === "Inference"
 
@@ -158,12 +146,7 @@ object resulting from the inference to it. Its fields are parsed and saved on di
 
 ## Custom Fields
 
-Besides regular fields in
+Besides regular fields in [`sv.Detections`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections), [`sv.CSVSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink) also allows you to add custom information to each row, which can be passed via the `custom_data` dictionary. Let's utilize this feature to save information about the frame index from which the detections originate.
-[`sv.Detections`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections),
-[`sv.CSVSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink)
-also allows you to add custom information to each row, which can be passed via the
-`custom_data` dictionary. Let's utilize this feature to save information about the
-frame index from which the detections originate.
 
 === "Inference"
 
@@ -235,11 +218,7 @@ frame index from which the detections originate.
 
 ## Save Detections as JSON
 
-If you prefer to save the result in a `.JSON` file instead of a `.CSV` file, all you
+If you prefer to save the result in a `.JSON` file instead of a `.CSV` file, all you need to do is replace [`sv.CSVSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink) with [`sv.JSONSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.json_sink.JSONSink).
-need to do is replace
-[`sv.CSVSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.csv_sink.CSVSink)
-with
-[`sv.JSONSink`](https://supervision.roboflow.com/latest/detection/tools/save_detections/#supervision.detection.tools.json_sink.JSONSink).
 
 === "Inference"
 

docs/how_to/track_objects.md

@@ -13,20 +13,11 @@ date_modified: 2026-04-22
 
 # Track Objects
 
-Leverage Supervision's advanced capabilities for enhancing your video analysis by
+Leverage Supervision's advanced capabilities for enhancing your video analysis by seamlessly [tracking](https://supervision.roboflow.com/latest/trackers/) objects recognized by a multitude of object detection, segmentation and keypoint 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.
-seamlessly [tracking](https://supervision.roboflow.com/latest/trackers/) objects recognized by
-a multitude of object detection, segmentation and keypoint 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.
 
 ## Object Detection & Segmentation
 
-To make it easier for you to follow our tutorial download the video we will use as an
+To make it easier for you to follow our tutorial download the video we will use as an example. You can do this using the [`supervision.assets`](https://supervision.roboflow.com/latest/assets/) module included in the base package.
-example. You can do this using the
-[`supervision.assets`](https://supervision.roboflow.com/latest/assets/) module included in the base package.
 
 This section demonstrates how to detect and segment objects in video frames using YOLOv8 with either the Inference or Ultralytics package. You will download a sample video, define a per-frame callback function that runs model prediction, and process the entire video to produce an annotated output file.
 
@@ -42,16 +33,9 @@ download_assets(VideoAssets.PEOPLE_WALKING)
 
 ### Run Inference
 
-First, you'll need to obtain predictions from your object detection or segmentation
+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/latest/how_to/detect_and_annotate/#load-predictions-into-supervision) for guidance on how to plug in other models.
-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/latest/how_to/detect_and_annotate/#load-predictions-into-supervision)
-for guidance on how to plug in other models.
 
-We will define a `callback` function, which will process each frame of the video
+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.
-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.
 
 !!! tip
 
@@ -107,11 +91,7 @@ it will be modified to include tracking, labeling, and trace annotations.
 
 ### Tracking
 
-After running inference and obtaining predictions, the next step is to track the
+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/latest/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.
-detected objects throughout the video. Utilizing Supervision’s
-[`sv.ByteTrack`](https://supervision.roboflow.com/latest/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"
 
@@ -163,11 +143,7 @@ enabling the continuous following of the object's motion path across different f
 
 ### Annotate Video with Tracking IDs
 
-Annotating the video with tracking IDs helps in distinguishing and following each object
+Annotating the video with tracking IDs helps in distinguishing and following each object distinctly. With the [`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator) in Supervision, we can overlay the tracker IDs and class labels on the detected objects, offering a clear visual representation of each object's class and unique identifier.
-distinctly. With the
-[`sv.LabelAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.LabelAnnotator)
-in Supervision, we can overlay the tracker IDs and class labels on the detected objects,
-offering a clear visual representation of each object's class and unique identifier.
 
 === "Ultralytics"
 
@@ -245,11 +221,7 @@ offering a clear visual representation of each object's class and unique identif
 
 ### Annotate Video with Traces
 
-Adding traces to the video involves overlaying the historical paths of the detected
+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/latest/detection/annotators/#supervision.annotators.core.TraceAnnotator), allows for visualizing the trajectories of objects, helping in understanding the movement patterns and interactions between objects in the video.
-objects. This feature, powered by the
-[`sv.TraceAnnotator`](https://supervision.roboflow.com/latest/detection/annotators/#supervision.annotators.core.TraceAnnotator),
-allows for visualizing the trajectories of objects, helping in understanding the
-movement patterns and interactions between objects in the video.
 
 === "Ultralytics"
 
@@ -335,8 +307,7 @@ movement patterns and interactions between objects in the video.
 
 Models aren't limited to object detection and segmentation. Keypoint detection allows for detailed analysis of body joints and connections, especially valuable for applications like human pose estimation. This section introduces keypoint tracking. We'll walk through the steps of annotating keypoints, converting them into bounding box detections compatible with `ByteTrack`, and applying detection smoothing for enhanced stability.
 
-To make it easier for you to follow our tutorial, let's download the video we will use as an
+To make it easier for you to follow our tutorial, let's download the video we will use as an example. You can do this using the [`supervision.assets`](https://supervision.roboflow.com/latest/assets/) module included in the base package.
-example. You can do this using the [`supervision.assets`](https://supervision.roboflow.com/latest/assets/) module included in the base package.
 
 ```python
 from supervision.assets import download_assets, VideoAssets
@@ -350,8 +321,7 @@ download_assets(VideoAssets.SKIING)
 
 ### Keypoint Detection
 
-First, you'll need to obtain predictions from your keypoint detection model. In this tutorial, we are using the YOLOv8 model as an example. However,
+First, you'll need to obtain predictions from your keypoint detection 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/latest/keypoint/core/) for guidance on how to plug in other models.
-Supervision is versatile and compatible with various models. Check this [link](https://supervision.roboflow.com/latest/keypoint/core/) 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.
 

docs/index.md

@@ -45,17 +45,13 @@ We write your reusable computer vision tools. Whether you need to load your data
 
 ## 💻 Install
 
-You can install `supervision` in a
+You can install `supervision` in a [**Python>=3.9**](https://www.python.org/) environment.
-[**Python>=3.9**](https://www.python.org/) environment.
 
 !!! example "Installation"
 
     === "pip (recommended)"
 
-        [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
+        [![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)](../LICENSE.md) [![python-version](https://img.shields.io/pypi/pyversions/supervision)](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)](../LICENSE.md)
-        [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
 
         ```bash
         pip install supervision
@@ -63,10 +59,7 @@ You can install `supervision` in a
 
     === "poetry"
 
-        [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
+        [![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)](../LICENSE.md) [![python-version](https://img.shields.io/pypi/pyversions/supervision)](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)](../LICENSE.md)
-        [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
 
         ```bash
         poetry add supervision
@@ -74,10 +67,7 @@ You can install `supervision` in a
 
     === "uv"
 
-        [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
+        [![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)](../LICENSE.md) [![python-version](https://img.shields.io/pypi/pyversions/supervision)](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)](../LICENSE.md)
-        [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
 
         ```bash
         uv pip install supervision
@@ -91,10 +81,7 @@ You can install `supervision` in a
 
     === "rye"
 
-        [![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision)
+        [![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)](../LICENSE.md) [![python-version](https://img.shields.io/pypi/pyversions/supervision)](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)](../LICENSE.md)
-        [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)
 
         ```bash
         rye add supervision

examples/count_people_in_zone/README.md

@@ -1,14 +1,10 @@
 # count people in zone
 
-[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-detect-and-count-objects-in-polygon-zone.ipynb)
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-detect-and-count-objects-in-polygon-zone.ipynb) [![YouTube](https://badges.aleen42.com/src/youtube.svg)](https://www.youtube.com/watch?v=l_kf9CfZ_8M)
-[![YouTube](https://badges.aleen42.com/src/youtube.svg)](https://www.youtube.com/watch?v=l_kf9CfZ_8M)
 
 ## 👋 hello
 
-This demo is a video analysis tool that counts and highlights objects in specific zones
+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.
-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
 
@@ -44,48 +40,33 @@ https://github.com/roboflow/supervision/assets/26109316/f84db7b5-79e2-4142-a1da-
 
 - ultralytics
 
-    - `--source_weights_path` (optional): The path to the YOLO model's weights file.
+    - `--source_weights_path` (optional): The path to the YOLO model's weights file. Defaults to `"yolov8x.pt"` if not specified.
-        Defaults to `"yolov8x.pt"` if not specified.
 
-    - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
+    - `--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.
-        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.
+    - `--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.
-        If not provided, the processed video will be displayed in real-time.
 
-    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model to filter detections. Default is `0.3`.
-        to filter detections. Default is `0.3`.
 
-    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold for the model. Default is `0.7`.
-        for the model. Default is `0.7`.
 
 - inference
 
-    - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+    - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key) to acquire your `API KEY`.
-        directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-        variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-        to acquire your `API KEY`.
 
-    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default value is `"yolov8x-1280"`.
-        value is `"yolov8x-1280"`.
 
-    - `--zone_configuration_path`: Specifies the path to the JSON file containing zone
+    - `--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.
-        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.
+    - `--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.
-        If not provided, the processed video will be displayed in real-time.
 
-    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model to filter detections. Default is `0.3`.
-        to filter detections. Default is `0.3`.
 
-    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold for the model. Default is `0.7`.
-        for the model. Default is `0.7`.
 
 ## 📌 zone configuration
 
@@ -121,12 +102,6 @@ https://github.com/roboflow/supervision/assets/26109316/f84db7b5-79e2-4142-a1da-
 
 This demo integrates two main components, each with its own licensing:
 
-- ultralytics: The object detection model used in this demo, YOLOv8, is distributed
+- ultralytics: The object detection model used in this demo, YOLOv8, is distributed under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE). You can find more details about this license here.
-    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-    You can find more details about this license here.
 
-- supervision: The analytics code that powers the zone-based analysis in this demo is
+- supervision: The analytics code that powers the zone-based analysis in this demo is based on the Supervision library, which is licensed under the [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This makes the Supervision part of the code fully open source and freely usable in your projects.
-    based on the Supervision library, which is licensed under the
-    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-    makes the Supervision part of the code fully open source and freely usable in your
-    projects.

examples/heatmap_and_track/README.md

@@ -2,9 +2,7 @@
 
 ## 👋 hello
 
-This script performs heatmap and tracking analysis using YOLOv8, an object-detection method and
+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.
-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
 
@@ -30,18 +28,11 @@ supervision package for multiple tasks such as drawing heatmap annotations, trac
 
 ## 🛠️ script arguments
 
-- `--source_weights_path`: Required. Specifies the path to the weights file for the
+- `--source_weights_path`: Required. Specifies the path to the weights file for the YOLO model. This file contains the trained model data necessary for object detection.
-    YOLO model. This file contains the trained model data necessary for object detection.
+- `--source_video_path` (optional): The path to the source video file that will be analyzed. This is the input video on which crowd analysis will be performed. If not specified default is `people-walking.mp4` from supervision assets
-- `--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
+- `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model to filter detections. Default is `0.3`. This determines how confident the model should be to recognize an object in the video.
-    to filter detections. Default is `0.3`. This determines how confident the model should
+- `--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.
-    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_activation_threshold` (optional): Detection confidence threshold for track activation.
@@ -63,12 +54,6 @@ python script.py \
 
 This demo integrates two main components, each with its own licensing:
 
-- ultralytics: The object detection model used in this demo, YOLOv8, is distributed
+- ultralytics: The object detection model used in this demo, YOLOv8, is distributed under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE). You can find more details about this license here.
-    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-    You can find more details about this license here.
 
-- supervision: The analytics code that powers the zone-based analysis in this demo is
+- supervision: The analytics code that powers the zone-based analysis in this demo is based on the Supervision library, which is licensed under the [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This makes the Supervision part of the code fully open source and freely usable in your projects.
-    based on the Supervision library, which is licensed under the
-    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-    makes the Supervision part of the code fully open source and freely usable in your
-    projects.

examples/speed_estimation/README.md

@@ -1,21 +1,14 @@
 # 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)
+[![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)
-[![YouTube](https://badges.aleen42.com/src/youtube.svg)](https://youtu.be/uWP6UjDeZvY)
 
 ## 👋 hello
 
-This example performs speed estimation analysis using various object-detection models
+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.
-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]
+> [!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).
-> 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
 
@@ -47,32 +40,19 @@ https://github.com/roboflow/supervision/assets/26109316/d50118c1-2ae4-458d-915a-
 
 ## 🛠️ script arguments
 
-- `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+- `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key) to acquire your `API KEY`.
-    directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-    variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-    to acquire your `API KEY`.
 
-- `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+- `--model_id` (optional): Designates the Roboflow model ID to be used. The default value is `"yolov8x-1280"`.
-    value is `"yolov8x-1280"`.
 
-- `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
+- `--source_weights_path`: Required. Specifies the path to the YOLO model's weights file, which is essential for the object detection process. This file contains the data that the model uses to identify objects in the video.
-    file, which is essential for the object detection process. This file contains the
-    data that the model uses to identify objects in the video.
 
-- `--source_video_path`: Required. The path to the source video file that will be
+- `--source_video_path`: Required. The path to the source video file that will be analyzed. This is the input video on which traffic flow analysis will be performed.
-    analyzed. This is the input video on which traffic flow analysis will be performed.
 
-- `--target_video_path`: The path to save the output video with
+- `--target_video_path`: The path to save the output video with annotations. If not specified, the processed video will be displayed in real-time without being saved.
-    annotations. If not specified, the processed video will be displayed in real-time
-    without being saved.
 
-- `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO
+- `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model to filter detections. Default is `0.3`. This determines how confident the model should be to recognize an object in the video.
-    model to filter detections. Default is `0.3`. This determines how confident the
-    model should be to recognize an object in the video.
 
-- `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+- `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold for the model. Default is 0.7. This value is used to manage object detection accuracy, particularly in distinguishing between different objects.
-    for the model. Default is 0.7. This value is used to manage object detection
-    accuracy, particularly in distinguishing between different objects.
 
 ## ⚙️ run
 
@@ -111,12 +91,6 @@ https://github.com/roboflow/supervision/assets/26109316/d50118c1-2ae4-458d-915a-
 
 This demo integrates two main components, each with its own licensing:
 
-- ultralytics: The object detection model used in this demo, YOLOv8, is distributed
+- ultralytics: The object detection model used in this demo, YOLOv8, is distributed under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE). You can find more details about this license here.
-    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-    You can find more details about this license here.
 
-- supervision: The analytics code that powers the zone-based analysis in this demo is
+- supervision: The analytics code that powers the zone-based analysis in this demo is based on the Supervision library, which is licensed under the [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This makes the Supervision part of the code fully open source and freely usable in your projects.
-    based on the Supervision library, which is licensed under the
-    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-    makes the Supervision part of the code fully open source and freely usable in your
-    projects.

examples/time_in_zone/README.md

@@ -4,10 +4,7 @@
 
 ## 👋 hello
 
-Practical demonstration on leveraging computer vision for analyzing wait times and
+Practical demonstration on leveraging computer vision for analyzing wait times and monitoring the duration that objects or individuals spend in predefined areas of video frames. This example project, perfect for retail analytics or traffic management applications.
-monitoring the duration that objects or individuals spend in predefined areas of video
-frames. This example project, perfect for retail analytics or traffic management
-applications.
 
 https://github.com/roboflow/supervision/assets/26109316/d051cc8a-dd15-41d4-aa36-d38b86334c39
 
@@ -59,9 +56,7 @@ python scripts/download_from_youtube.py \
 
 ### `stream_from_file`
 
-This script allows you to stream video files from a directory. It's an awesome way to
+This script allows you to stream video files from a directory. It's an awesome way to mock a live video stream for local testing. Video will be streamed in a loop under `rtsp://localhost:8554/live0.stream` URL. This script requires docker to be installed.
-mock a live video stream for local testing. Video will be streamed in a loop under
-`rtsp://localhost:8554/live0.stream` URL. This script requires docker to be installed.
 
 - `--video_directory`: Directory containing video files to stream.
 - `--number_of_streams`: Number of video files to stream.
@@ -80,10 +75,7 @@ python scripts/stream_from_file.py \
 
 ### `draw_zones`
 
-If you want to test zone time in zone analysis on your own video, you can use this
+If you want to test zone time in zone analysis on your own video, you can use this script to design custom zones and save results as a JSON file. The script will open a window where you can draw polygons on the source image or video file. The polygons will be saved as a JSON file.
-script to design custom zones and save results as a JSON file. The script will open a
-window where you can draw polygons on the source image or video file. The polygons will
-be saved as a JSON file.
 
 - `--source_path`: Path to the source image or video file for drawing polygons.
 - `--zone_configuration_path`: Path where the polygon annotations will be saved as a JSON file.
@@ -324,12 +316,6 @@ python ultralytics_stream_example.py \
 
 This demo integrates two main components, each with its own licensing:
 
-- ultralytics: The object detection model used in this demo, YOLOv8, is distributed
+- ultralytics: The object detection model used in this demo, YOLOv8, is distributed under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE). You can find more details about this license here.
-    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-    You can find more details about this license here.
 
-- supervision: The analytics code that powers the zone-based analysis in this demo is
+- supervision: The analytics code that powers the zone-based analysis in this demo is based on the Supervision library, which is licensed under the [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This makes the Supervision part of the code fully open source and freely usable in your projects.
-    based on the Supervision library, which is licensed under the
-    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-    makes the Supervision part of the code fully open source and freely usable in your
-    projects.

examples/tracking/README.md

@@ -2,8 +2,7 @@
 
 ## 👋 hello
 
-This script provides functionality for processing videos using YOLOv8 for object
+This script provides functionality for processing videos using YOLOv8 for object detection and Supervision for tracking and annotation.
-detection and Supervision for tracking and annotation.
 
 ## 💻 install
 
@@ -31,47 +30,29 @@ detection and Supervision for tracking and annotation.
 
 - ultralytics
 
-    - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
+    - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights file, which is essential for the object detection process. This file contains the data that the model uses to identify objects in the video.
-        file, which is essential for the object detection process. This file contains the data
-        that the model uses to identify objects in the video.
 
-    - `--source_video_path`: Required. The path to the source video file to be processed.
+    - `--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.
-        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
+    - `--target_video_path`: Required. The path where the processed video, with annotations added, will be saved. This is your output video file.
-        added, will be saved. This is your output video file.
 
-    - `--confidence_threshold` (optional): Sets the confidence level at which the model
+    - `--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.
-        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
+    - `--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.
-        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
+    - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key) to acquire your `API KEY`.
-        directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-        variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-        to acquire your `API KEY`.
 
-    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default value is `"yolov8x-1280"`.
-        value is `"yolov8x-1280"`.
 
-    - `--source_video_path`: Required. The path to the source video file to be processed.
+    - `--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.
-        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
+    - `--target_video_path`: Required. The path where the processed video, with annotations added, will be saved. This is your output video file.
-        added, will be saved. This is your output video file.
 
-    - `--confidence_threshold` (optional): Sets the confidence level at which the model
+    - `--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.
-        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
+    - `--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.
-        for the model, defaulting to `0.7`. This parameter helps in differentiating between
-        distinct objects, especially in crowded scenes.
 
 ## ⚙️ run
 
@@ -97,12 +78,6 @@ detection and Supervision for tracking and annotation.
 
 This demo integrates two main components, each with its own licensing:
 
-- ultralytics: The object detection model used in this demo, YOLOv8, is distributed
+- ultralytics: The object detection model used in this demo, YOLOv8, is distributed under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE). You can find more details about this license here.
-    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-    You can find more details about this license here.
 
-- supervision: The analytics code that powers the zone-based analysis in this demo is
+- supervision: The analytics code that powers the zone-based analysis in this demo is based on the Supervision library, which is licensed under the [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This makes the Supervision part of the code fully open source and freely usable in your projects.
-    based on the Supervision library, which is licensed under the
-    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-    makes the Supervision part of the code fully open source and freely usable in your
-    projects.

examples/traffic_analysis/README.md

@@ -2,9 +2,7 @@
 
 ## 👋 hello
 
-This script performs traffic flow analysis using YOLOv8, an object-detection method and
+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.
-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
 
@@ -40,49 +38,29 @@ https://github.com/roboflow/supervision/assets/26109316/c9436828-9fbf-4c25-ae8c-
 
 - ultralytics
 
-    - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights
+    - `--source_weights_path`: Required. Specifies the path to the YOLO model's weights file, which is essential for the object detection process. This file contains the data that the model uses to identify objects in the video.
-        file, which is essential for the object detection process. This file contains the
-        data that the model uses to identify objects in the video.
 
-    - `--source_video_path`: Required. The path to the source video file that will be
+    - `--source_video_path`: Required. The path to the source video file that will be analyzed. This is the input video on which traffic flow analysis will be performed.
-        analyzed. This is the input video on which traffic flow analysis will be performed.
 
-    - `--target_video_path` (optional): The path to save the output video with
+    - `--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.
-        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
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model to filter detections. Default is `0.3`. This determines how confident the model should be to recognize an object in the video.
-        model to filter detections. Default is `0.3`. This determines how confident the
-        model should be to recognize an object in the video.
 
-    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold for the model. Default is 0.7. This value is used to manage object detection accuracy, particularly in distinguishing between different objects.
-        for the model. Default is 0.7. This value is used to manage object detection
-        accuracy, particularly in distinguishing between different objects.
 
 - inference
 
-    - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided
+    - `--roboflow_api_key` (optional): The API key for Roboflow services. If not provided directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key) to acquire your `API KEY`.
-        directly, the script tries to fetch it from the `ROBOFLOW_API_KEY` environment
-        variable. Follow [this guide](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)
-        to acquire your `API KEY`.
 
-    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default
+    - `--model_id` (optional): Designates the Roboflow model ID to be used. The default value is `"vehicle-count-in-drone-video/6"`.
-        value is `"vehicle-count-in-drone-video/6"`.
 
-    - `--source_video_path`: Required. The path to the source video file that will be
+    - `--source_video_path`: Required. The path to the source video file that will be analyzed. This is the input video on which traffic flow analysis will be performed.
-        analyzed. This is the input video on which traffic flow analysis will be performed.
 
-    - `--target_video_path` (optional): The path to save the output video with
+    - `--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.
-        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
+    - `--confidence_threshold` (optional): Sets the confidence threshold for the YOLO model to filter detections. Default is `0.3`. This determines how confident the model should be to recognize an object in the video.
-        model to filter detections. Default is `0.3`. This determines how confident the
-        model should be to recognize an object in the video.
 
-    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold
+    - `--iou_threshold` (optional): Specifies the IOU (Intersection Over Union) threshold for the model. Default is 0.7. This value is used to manage object detection accuracy, particularly in distinguishing between different objects.
-        for the model. Default is 0.7. This value is used to manage object detection
-        accuracy, particularly in distinguishing between different objects.
 
 ## ⚙️ run
 
@@ -112,12 +90,6 @@ https://github.com/roboflow/supervision/assets/26109316/c9436828-9fbf-4c25-ae8c-
 
 This demo integrates two main components, each with its own licensing:
 
-- ultralytics: The object detection model used in this demo, YOLOv8, is distributed
+- ultralytics: The object detection model used in this demo, YOLOv8, is distributed under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE). You can find more details about this license here.
-    under the [AGPL-3.0 license](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
-    You can find more details about this license here.
 
-- supervision: The analytics code that powers the zone-based analysis in this demo is
+- supervision: The analytics code that powers the zone-based analysis in this demo is based on the Supervision library, which is licensed under the [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This makes the Supervision part of the code fully open source and freely usable in your projects.
-    based on the Supervision library, which is licensed under the
-    [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). This
-    makes the Supervision part of the code fully open source and freely usable in your
-    projects.