feat(depth): load depth maps from Inference, Ultralytics, Transformers and dataset files

[cfviotti]

One frame, three sources, one line each to load. Left: Depth Anything V3 through Roboflow's hosted API. Middle: YOLO26 depth, in metres; it sees the opening in the rock as far and everything else as close. Right: the dataset's true depth, read from its 16-bit PNG.

▶️📓 Notebook Playground Demo (all 4 PRs together)

Description

Every depth model returns its map in its own shape and unit: a base64 16-bit PNG normalised to 0..1, a torch tensor in metres, a predicted_depth of unknown kind. These loaders turn each into a sv.DepthMap with the right kind, the same way sv.Detections.from_ultralytics does for boxes:

depth_map = sv.DepthMap.from_inference(result)            # depth models served by Roboflow Inference
depth_map = sv.DepthMap.from_ultralytics(results[0])      # YOLO26 depth, metres
depth_map = sv.DepthMap.from_transformers(output, kind="relative_inverse")
depth_map = sv.DepthMap.from_png16("disp_occ_0/000000_10.png", scale=256, kind="disparity_px")  # KITTI
depth_map = sv.DepthMap.from_pfm("disp0GT.pfm", kind="disparity_px")                            # Middlebury

Part 4 of 4. Needs PR 1 (#2691).

Motivation and Context

Follows #2691, where a map is built from an array by hand.

Changes Made

• from_inference: every depth_map_format (JSON lists, 8- or 16-bit PNG, and the array the SDK and Workflows decode), plus an in-process model's response, as relative_inverse.
• from_ultralytics: result.depth.data, metres at the original image size.
• from_transformers: predicted_depth from the depth-estimation pipeline or a model output. Transformers does not say what a model predicts, so kind is required.
• from_png16(path, scale, kind): 16-bit PNGs divided by the dataset's scale, with 0 as no depth (KITTI disparity uses 256, Ultralytics depth datasets 1000 by default).
• from_pfm(path, kind): Middlebury and SceneFlow PFM files, with unknown values as no depth.
• Docs: the how-to's loading section, docstring examples and a changelog entry.

Testing

pytest tests/depth --doctest-modules src/supervision/depth   63 passed (24 new)
pytest                                                       4856 passed, 79 skipped
pre-commit run                                               all hooks pass
mkdocs build                                                 no new warnings

• Added/updated tests, and the full suite passes locally
• Updated docs (docstrings / mkdocs entry) for new or changed public API
• Added a changelog entry in docs/changelog.md under Unreleased
• from_inference on hosted depth-anything-v3/small, in both png16 and JSON formats: full image size, every pixel valid, near objects warm (image above)
• from_ultralytics on yolo26n-depth.pt: metres at the image's exact size (image above)
• Tests are offline: model outputs are built in the tests, no downloads

Additional Notes

• inference, ultralytics, transformers and torch are not imported by supervision. The loaders read the objects these libraries return.

[Copilot]

🟡 Changes recommended

Workflow tensors, PFM scale factors, and non-PNG payload validation are not handled correctly.

3 open findings

• Convert normalized depth tensors to CPU NumPy arrays · New
• Reject non-PNG images in depth payloads · New
• Apply and validate PFM scale magnitude · New

What changed in this PR

Adds standardized DepthMap loaders for model outputs and common depth dataset formats.

Changes:

• Adds Inference, Ultralytics, Transformers, PNG16, and PFM loaders.
• Adds offline tests for formats, validation, and byte order.
• Updates depth documentation, examples, and changelog.

Assessment: Code quality 3/5 · Testing 4/5 · Documentation 4/5

File	Description
src/​supervision/​depth/​core.py	Adds model and file loader APIs.
src/​supervision/​depth/​readers.py	Adds PNG16 and PFM readers.
src/​supervision/​depth/​annotators.py	Updates the annotator example.
tests/​depth/​test_core.py	Tests new DepthMap loaders.
tests/​depth/​test_readers.py	Tests PFM parsing and validation.
docs/​how_to/​visualize_depth.md	Documents supported loading workflows.
docs/​depth/​core.md	Updates API-page metadata.
docs/​changelog.md	Records the new loaders.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 98.01325% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 93%. Comparing base (2807e71) to head (c756bce).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop   #2694    +/-   ##
========================================
  Coverage       93%     93%            
========================================
  Files           82      83     +1     
  Lines        12822   12973   +151     
========================================
+ Hits         11967   12115   +148     
- Misses         855     858     +3     

🚀 New features to boost your workflow:

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

[Copilot]

🟡 Changes recommended

The PFM reader ignores the header’s scale magnitude, producing incorrect values for valid non-unit scales.

2 open findings

• Apply PFM scale magnitude when decoding raster samples · New
• Document applying PFM scale magnitude to decoded samples · New

3 resolved since last review

• Apply and validate PFM scale magnitude
• Reject non-PNG images in depth payloads
• Convert normalized depth tensors to CPU NumPy arrays

🧠 Review effort: Balanced