fix: close out remaining review findings

[Borda]

This pull request introduces several improvements and fixes across the codebase, focusing on enhancing documentation, improving API usability, and increasing numerical precision for large-scale image processing. The main highlights are the addition of usage examples to many public functions, a new reset() method for the HeatMapAnnotator, and improved precision in the box_iou_batch function for handling large coordinate values.

API Improvements and Fixes:

• sv.HeatMapAnnotator now includes a reset() method to clear accumulated heat, allowing the same annotator instance to be reused across independent streams without carrying over state.
• sv.box_iou_batch now performs area and intersection calculations in float64 before returning float32, preserving precision for very large coordinates (such as those found in GeoTIFF images). [1] [2]
• Legacy sv.MeanAveragePrecision now raises a ValueError if predictions reference image IDs not present in the ground-truth COCO set, rather than relying on an assert that could be skipped in optimized Python mode.

Documentation Enhancements:

• Added usage examples to a wide range of public functions, including color conversion utilities (hex_to_rgba, rgba_to_hex, is_valid_hex), COCO utilities, mask and polygon conversion functions, NMS utilities, and drawing functions. These examples make it easier for users to understand and adopt the API. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19]

Changelog Updates:

• The changelog (docs/changelog.md) has been updated to reflect the new features, bug fixes, and deprecation warnings, ensuring users are informed about the latest changes and migration notes.

Documentation Structure:

• New documentation entries for is_compressed_rle and calculate_masks_centroids have been added, improving discoverability of these utilities. [1] [2]

These changes collectively improve the reliability, usability, and user-friendliness of the codebase.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87%. Comparing base (8dedc34) to head (c52d37f).

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2418   +/-   ##
=======================================
  Coverage       87%     87%           
=======================================
  Files           71      71           
  Lines        10446   10458   +12     
=======================================
+ Hits          9048    9071   +23     
+ Misses        1398    1387   -11     

🚀 New features to boost your workflow:

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

[Copilot]

Pull request overview

This pull request tightens up several API behaviors in supervision while improving user-facing documentation and examples, with a focus on metrics/annotators usability and numerical stability in overlap computations.

Changes:

• Added HeatMapAnnotator.reset() to explicitly clear accumulated heat for reuse across independent streams.
• Improved box_iou_batch numerical robustness for large coordinate magnitudes by using higher-precision intermediates and added a regression test.
• Expanded docstrings, docs pages, and changelog entries; added/updated tests for metrics utilities and dataset export validation.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/metrics/utils/test_utils.py	Adds coverage for the pandas “metrics extra” guard (ensure_pandas_installed).
tests/metrics/utils/test_matching.py	Adds unit tests for greedy one-to-one IoU matching behavior.
tests/metrics/test_mean_average_recall.py	Switches to default_rng for deterministic, local RNG use in integration test.
tests/metrics/test_mean_average_precision.py	Adds validation test for EvaluationDataset.load_predictions unknown image IDs.
tests/metrics/test_core.py	Adds tests for Metric ABC behavior and shared enums.
tests/detection/utils/test_iou_and_nms.py	Adds regression test for box_iou_batch precision above float32’s integer-exact limit.
tests/detection/test_compact_mask.py	Improves parametrization IDs and adds/clarifies test docstrings for CompactMask behaviors.
tests/dataset/formats/test_labelme.py	Adds test to ensure LabelMe export rejects basename/stem collisions.
tests/annotators/test_core.py	Adds test verifying HeatMapAnnotator.reset() clears accumulated heat.
src/supervision/utils/conversion.py	Adds docstring usage examples for Pillow↔OpenCV conversion helpers.
src/supervision/metrics/mean_average_precision.py	Replaces an assert with a ValueError for invalid prediction image IDs (robust under python -O).
src/supervision/draw/utils.py	Adds usage examples to core drawing utilities.
src/supervision/detection/utils/polygons.py	Adds docstring example for polygon area filtering.
src/supervision/detection/utils/masks.py	Adds docstring examples for centroid calculation and ROI extraction.
src/supervision/detection/utils/iou_and_nms.py	Uses float64 intermediates for large-coordinate IoU computations; adds multiple docstring examples.
src/supervision/detection/utils/converters.py	Adds docstring examples for box/polygon/mask conversion helpers.
src/supervision/detection/tools/polygon_zone.py	Adds a docstring example for PolygonZoneAnnotator.
src/supervision/dataset/formats/coco.py	Adds a docstring example for COCO class index mapping helper.
src/supervision/annotators/utils.py	Adds docstring examples for hex/RGBA conversion and validation helpers.
src/supervision/annotators/core.py	Adds HeatMapAnnotator.reset() to clear accumulated heat mask.
docs/detection/utils/masks.md	Adds docs entry for calculate_masks_centroids.
docs/detection/utils/converters.md	Adds docs entry for is_compressed_rle.
docs/changelog.md	Documents the new/reset behavior, precision fix, and the updated validation behavior.

[kounelisagis]

Left a couple of notes inline, nothing blocking.