feat: add image URL loader

[Erol444]

Summary

Adds load_image_from_url() to supervision.utils.image and exports it from the top-level supervision package. The helper validates and normalizes HTTP(S) URLs, downloads the image with requests, decodes it through OpenCV, and raises clear errors for invalid URLs, request failures, or undecodable image bytes.

Also adds mkdocs API documentation and focused unit tests for successful decoding, invalid image bytes, request failures, and non-HTTP URL rejection.

Validation

• uv run --frozen pytest tests/utils/test_image.py tests/utils/test_video.py
• SKIP=mypy uv run --frozen pre-commit run --files src/supervision/utils/internal.py src/supervision/utils/image.py src/supervision/utils/video.py src/supervision/__init__.py tests/utils/test_image.py tests/utils/test_video.py docs/utils/image.md docs/utils/video.md
• git diff --check

Note: the local mypy hook was skipped because it fails before checking this code due to a NumPy stub syntax issue under the repo's configured Python 3.9 target.

[codecov]

Codecov Report

❌ Patch coverage is 91.52542% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 87%. Comparing base (5b4c8b6) to head (5b3d4ac).
⚠️ Report is 6 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2372   +/-   ##
=======================================
  Coverage       86%     87%           
=======================================
  Files           70      70           
  Lines        10175   10234   +59     
=======================================
+ Hits          8799    8853   +54     
- Misses        1376    1381    +5     

🚀 New features to boost your workflow:

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

[Copilot]

Pull request overview

Adds a new convenience loader for fetching images over HTTP(S) into OpenCV/NumPy (load_image_from_url) and wires it into the public API, along with unit tests and API docs.

Changes:

• Introduces load_image_from_url() in supervision.utils.image (URL validation, download via requests, decode via OpenCV, optional on-disk caching).
• Adds prepare_url() helper in supervision.utils.internal for HTTP(S) URL normalization/validation.
• Exports the new helper from supervision.__init__, and documents/tests the new behavior.

Quality / Testing / Docs (n/5):

• Code quality: 4/5
• Testing: 5/5
• Docs: 3/5

Reviewed changes

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

Show a summary per file

File	Description
tests/utils/test_image.py	Adds focused unit tests for URL loading, caching behavior, and failure modes.
src/supervision/utils/internal.py	Adds shared URL normalization/validation helper (prepare_url).
src/supervision/utils/image.py	Implements load_image_from_url (download/decode/cache) and related helpers.
src/supervision/init.py	Exposes load_image_from_url from the top-level package.
docs/utils/image.md	Adds mkdocs API entry for load_image_from_url.

[SkalskiP]

supervision already has an assets package for downloading files from our curated pool of images and videos. Since this new utility also downloads images, I think we should keep its behavior close to the existing assets flow.

In particular, it should use the same hashing strategy, cache files in the same location, and follow similar timeout, retry, and loading behavior.

At the moment, these two paths do not share any code, and their behavior is quite different.

I’d extract one small primitive into utils/file.py:

def _download_to_file(url: str, target: Path, *, timeout: float = 30.0, stream: bool = False) -> None:
    """Download `url` to `target` atomically using a temp file and `os.replace`."""

Then both load_image_from_url and download_assets would call it.

[SkalskiP]

utils/internal.py is focused on deprecation and introspection helpers. A URL normalizer used by a single caller feels out of place there.