Implemented headless install support

[robmarkcole]

What does this PR do?

• Added rfdetr[headless] in pyproject.toml, resolving to opencv-python-headless and supervision==0.20.x.
• Kept default installs unchanged with supervision>=0.20.0.
• Added a small metadata compatibility helper in detr.py so predict() still handles the older Supervision object used by the headless extra.
• Documented headless install in README.md, docs/learn/install.md, and AGENTS.md.
  Added tests for the new extra and legacy metadata behavior.

Address #531

Type of Change

• New feature (non-breaking change that adds functionality)

Testing

• uvx pre-commit run --all-files

• optional dependency tests passed

• pip and uv dry-runs for .[headless] resolve opencv-python-headless and not opencv-python

• focused predict metadata tests passed under both current Supervision and supervision==0.20.0

• I have tested this change locally

• I have added/updated tests for this change

Checklist

• [ x] My code follows the style guidelines of this project
• [ x] I have performed a self-review of my own code
• [ x] I have commented my code where necessary, particularly in hard-to-understand areas
• [ x] My changes generate no new warnings or errors
• [ x] I have updated the documentation accordingly (if applicable)

Additional Context

To be utilised by torchgeo/torchgeo#3625

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

Adds a supported “headless” installation path for RF-DETR so inference environments (e.g., Linux servers/Docker) can avoid GUI OpenCV system-library requirements, while keeping default installs unchanged.

Changes:

• Introduces rfdetr[headless] extra (OpenCV headless + pinned Supervision line) and sets core supervision>=0.20.0.
• Adds a small compatibility helper in RFDETR.predict() to attach source_image metadata when sv.Detections lacks .metadata.
• Documents headless installation and adds tests covering the new extra constraints and legacy metadata behavior.

Reviewed changes

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

Show a summary per file

File	Description
pyproject.toml	Adds headless extra (opencv-python-headless + supervision>=0.20.0,<0.21.0) and constrains core supervision to >=0.20.0.
src/rfdetr/detr.py	Adds _attach_detection_metadata() and uses it in predict() to support older Supervision Detections objects without .metadata.
tests/models/test_predict.py	Adds a regression test for legacy detections metadata attachment via _attach_detection_metadata().
tests/cli/test_optional_dependencies.py	Refactors extras reader + adds tests ensuring headless extra uses headless OpenCV and pins Supervision below 0.21.
README.md	Documents pip install "rfdetr[headless]" for headless inference environments.
docs/learn/install.md	Adds a “Headless” install tab with pip and uv commands.
AGENTS.md	Notes the new [headless] extra and the “clean environment” recommendation to avoid multiple cv2 providers.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77%. Comparing base (83c82aa) to head (08a03e7).
⚠️ Report is 14 commits behind head on develop.

❌ Your project check has failed because the head coverage (77%) is below the target coverage (95%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@          Coverage Diff           @@
##           develop   #999   +/-   ##
======================================
  Coverage       77%    77%           
======================================
  Files          102    102           
  Lines         9032   9038    +6     
======================================
+ Hits          6966   6972    +6     
  Misses        2066   2066           

🚀 New features to boost your workflow:

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

[Borda]

ERROR tests/benchmarks/test_training_synthetic.py::test_train_convergence_segmentation - AttributeError: module 'supervision' has no attribute 'draw_filled_polygon'
ERROR tests/benchmarks/test_training_synthetic.py::test_train_convergence_native_ptl - AttributeError: module 'supervision' has no attribute 'draw_filled_polygon'
ERROR tests/benchmarks/test_training_synthetic.py::test_train_convergence_rfdetr_api - AttributeError: module 'supervision' has no attribute 'draw_filled_polygon'

[robmarkcole]

@Borda I guess that ideally supervision would also be available as headless

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	opencv-python-headless@​4.13.0.92
	supervision@​0.20.0

View full report