fix(annotators): clip CropAnnotator boxes to the scene before cropping

[abhijithneilabraham]

Before submitting

• Self-reviewed the code
• Updated documentation, follow Google-style
  (https://google.github.io/styleguide/pyguide.html#383-functions-and-methods)
• Added docs entry for autogeneration (if new functions/classes)
• Added/updated tests
• All tests pass locally

Description

CropAnnotator.annotate passed raw detection coordinates into crop_image, which
slices with plain numpy indexing. A negative x_min or y_min wraps around and
produces an empty crop, and scale_image then feeds the zero-size image to
cv2.resize, which raises cv2.error. Boxes fully outside the frame and
zero-width or zero-area boxes crash the same way, so one degenerate detection
aborts annotation of the whole frame.

This PR clips boxes to the scene with the existing clip_boxes helper,
mirroring BlurAnnotator and PixelateAnnotator, and skips boxes that are empty
after clipping. Skipped boxes keep their detection index, so color lookup
stays aligned with the original detections.

For every input the old code handled without crashing, the output is
pixel-identical (verified byte-for-byte for in-bounds and
right/bottom-overshoot boxes). The only behavior change besides removing the
crash: a fully negative box such as [-50, -50, -10, -10] previously wrapped
around and silently pasted a crop of an unrelated image region; it is now
skipped.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)

Motivation and Context

Boxes at or beyond the frame border arise from supported workflows:
sv.pad_boxes produces negative coordinates for boxes near the frame edge, the
from_vlm connectors pass model coordinates through unclamped, and boxes land
fully outside the frame when detections computed at one resolution are
annotated onto another. The sibling annotators that slice the scene the same
way (BlurAnnotator, PixelateAnnotator) already clip; CropAnnotator was the
only one that did not.

Closes #2390

Changes Made

• Clip boxes to the scene in CropAnnotator.annotate using the existing
  clip_boxes helper before cropping
• Skip boxes whose width or height is zero after clipping instead of feeding
  empty crops to cv2.resize
• Move crop and scale into the per-detection loop so a degenerate box no
  longer prevents valid boxes from being drawn
• Add regression tests: five border-crossing boxes annotate without raising,
  four degenerate boxes are skipped leaving the scene unchanged, and a mixed
  valid/degenerate case still draws the valid box

Testing

• I have tested this code locally
• I have added unit tests that prove my fix is effective or that my
  feature works
• All new and existing tests pass

The new tests fail on current develop with cv2.error (7 failing cases) and
pass with the fix (13/13 in TestCropAnnotator). Full suite: 2459 passed, 1
skipped, including under pytest --cov=supervision.

Reproduce the original crash on develop:

  import numpy as np  
  import supervision as sv

  image = np.zeros((100, 100, 3), dtype=np.uint8)
  detections = sv.Detections(
      xyxy=np.array([[-5, 20, 40, 60]], dtype=np.float32),
      class_id=np.array([0]),   
  )

  sv.BlurAnnotator().annotate(image.copy(), detections)   # works
  sv.CropAnnotator().annotate(image.copy(), detections)   # cv2.error before 
  this PR

Google Colab (optional)

Colab link: N/A

Screenshots/Videos (optional)

N/A

Additional Notes

No public API changes and no new dependencies. crop_image itself still returns
a silently empty array for out-of-bounds input; clamping it was left out of
scope to keep this PR minimal, since callers other than CropAnnotator already
clip.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84%. Comparing base (f196e15) to head (443fec3).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2391   +/-   ##
=======================================
  Coverage       84%     84%           
=======================================
  Files           70      70           
  Lines        10004   10009    +5     
=======================================
+ Hits          8436    8442    +6     
+ Misses        1568    1567    -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 fixes CropAnnotator.annotate crashing when detections contain boxes that touch/cross the scene border (negative coords, fully out-of-frame, or degenerate/zero-area boxes). It aligns CropAnnotator with sibling annotators that already clamp boxes before NumPy slicing, preventing cv2.resize from receiving empty crops.

Changes:

• Clip detections.xyxy to the scene bounds via existing clip_boxes(...) before cropping.
• Skip detections that become empty after clipping (zero width/height) to avoid cv2.error.
• Add regression tests covering border-crossing, fully-outside/degenerate, and mixed valid+degenerate cases.

Assessment (n/5):

• Code quality: 5/5
• Testing: 5/5
• Docs: 5/5 (no public API change; existing docstrings remain applicable)

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/supervision/annotators/core.py	Clamp crop regions to the scene and skip degenerate boxes so annotation can’t crash on out-of-bounds slices.
tests/annotators/test_core.py	Adds coverage to ensure border/degenerate boxes don’t raise and are skipped appropriately.

[abhijithneilabraham]

@Borda is #2393 an alternate fix for this PR?