fix(docs): resolve review deprecation follow-ups

[Borda]

This pull request updates the documentation to clarify deprecation timelines, improve migration guidance for deprecated APIs (especially sv.ByteTrack), and enhance the docs for metrics and utility modules. It also introduces new or expanded API reference pages for several utility modules. The most important changes are summarized below.

Deprecation timeline updates and migration guidance:

• All references to deprecated APIs such as sv.ByteTrack, supervision.keypoint, and related arguments or modules have their removal versions delayed from 0.30.0 to 0.31.0 in the documentation, changelog, and deprecation notices. This gives users a longer transition window. [1] [2] [3] [4]
• Docs now consistently recommend migrating from sv.ByteTrack to the external ByteTrackTracker (from the trackers package) and clarify method renames. Prominent warnings and migration instructions are added in API references, how-to guides, and FAQs. [1] [2] [3]

Improved documentation for metrics and installation:

• All metrics-related documentation pages now instruct users to install the metrics extra (pip install "supervision[metrics]") before using metrics APIs. This is added to the main metrics, mean average precision, recall, F1 score, and related pages, as well as the FAQ. [1] [2] [3] [4] [5] [6] [7] [8]

New and expanded API reference pages:

• New API reference pages are added for utility modules, including supervision.utils.conversion (conversion between cv2 and Pillow images), and expanded for geometry types like Point, Rect, and Vector. [1] [2]
• The VLM (Vision-Language Model) utility documentation is expanded with references for VLM, LMM, and validate_vlm_parameters.

Changelog and description improvements:

• The changelog is updated to clarify the new deprecation/removal schedule and to highlight several bug fixes and behavior changes.
• The description of the mean average precision metric is updated to clarify support for boxes, masks, and oriented boxes.

These changes collectively improve migration clarity for users, ensure documentation is up-to-date with the latest deprecation schedules, and enhance discoverability of utility APIs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86%. Comparing base (072f784) to head (1d3e58f).

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2415   +/-   ##
=======================================
  Coverage       86%     86%           
=======================================
  Files           70      70           
  Lines        10330   10335    +5     
=======================================
+ Hits          8872    8878    +6     
+ Misses        1458    1457    -1     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR primarily updates the MkDocs documentation and API references to clarify deprecation timelines/migrations (notably sv.ByteTrack → external ByteTrackTracker) and to make metrics installation requirements more explicit. It also includes a handful of small library behavior/docs improvements (e.g., ImageSink write failure handling, Color validation, and a changed default for polygon approximation).

Changes:

• Standardize deprecation/migration guidance and delay several planned removals to 0.31.0 across docs and in-code deprecation notices.
• Update metrics docs to consistently instruct installing supervision[metrics] before using metrics APIs.
• Expand API reference coverage (new/expanded utility and geometry pages), plus small related code/test updates.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/utils/test_image.py	Adds regression test for ImageSink.save_image failure behavior.
tests/geometry/test_core.py	Adds test ensuring Position.list() preserves definition order.
tests/draw/test_color.py	Adds tests for Color rejecting out-of-range channel values.
tests/dataset/test_utils.py	Adds test asserting default polygon approximation percentage is 0.0.
src/supervision/utils/internal.py	Accepts corrected + legacy env var name for deprecation warning control.
src/supervision/utils/image.py	Raises on failed cv2.imwrite in ImageSink.save_image; adds class docstring.
src/supervision/tracker/byte_tracker/core.py	Delays ByteTrack removal to 0.31.0 and updates deprecation rendering.
src/supervision/metrics/mean_average_precision.py	Updates result docstring to reflect -1 sentinel behavior.
src/supervision/keypoint/core.py	Updates keypoint module deprecation removal version to 0.31.0.
src/supervision/keypoint/annotators.py	Updates keypoint module deprecation removal version to 0.31.0.
src/supervision/keypoint/init.py	Updates keypoint module deprecation removal version to 0.31.0.
src/supervision/geometry/core.py	Improves docstrings; makes Position.list() deterministic via list comprehension.
src/supervision/draw/color.py	Adds __post_init__ range validation for direct Color(...) construction.
src/supervision/detection/vlm.py	Updates LMM deprecation formatting for rendered docs.
src/supervision/detection/utils/boxes.py	Delays deprecated denormalize_boxes arg-remap removal to 0.31.0.
src/supervision/detection/line_zone.py	Adds/expands docstrings for line zone annotators.
src/supervision/dataset/utils.py	Delays RLE compatibility removals; changes default polygon simplification to 0.0.
mkdocs.yml	Adjusts nav labels and adds new docs pages to navigation.
docs/utils/geometry.md	Expands API reference page to include Point, Rect, and Vector.
docs/utils/conversion.md	New API reference page for conversion utilities (needs symbol-name corrections).
docs/trackers.md	Adds prominent ByteTrack deprecation warning in the tracker reference.
docs/metrics/recall.md	Adds supervision[metrics] install instructions.
docs/metrics/precision.md	Adds supervision[metrics] install instructions.
docs/metrics/mean_average_recall.md	Adds supervision[metrics] install instructions.
docs/metrics/mean_average_precision.md	Adds supervision[metrics] install instructions; clarifies supported targets.
docs/metrics/f1_score.md	Adds supervision[metrics] install instructions.
docs/metrics/common_values.md	Adds supervision[metrics] install instructions.
docs/how_to/track_objects.md	Adds sv.ByteTrack deprecation warning and migration notes.
docs/faq.md	Updates tracker + benchmarking answers with deprecation/metrics guidance.
docs/detection/utils/vlms.md	Expands VLM utils page to document VLM, LMM, and validate_vlm_parameters.
docs/detection/tools/inference_slicer.md	Adds API reference entry for WindowedRasterDataset.
docs/detection/metrics.md	Adds supervision[metrics] install instructions to legacy metrics page.
docs/deprecated.md	Updates deprecation list with consistent versioning and migration guidance.
docs/changelog.md	Notes deprecation schedule delay + highlights related fixes/behavior changes.
AGENTS.md	Updates keypoint alias deprecation removal version to 0.31.0.