Implemented headless install support by robmarkcole · Pull Request #999 · roboflow/rf-detr

robmarkcole · 2026-04-25T13:14:32Z

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 · 2026-04-25T13:14:39Z

All committers have signed the CLA.

Co-authored-by: Jirka Borovec <6035284+Borda@users.noreply.github.com>

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 · 2026-04-27T11:24:04Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81%. Comparing base (3fe9bab) to head (4adb64f).

❌ Your project check has failed because the head coverage (81%) 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       81%     81%           
=======================================
  Files          106     107    +1     
  Lines        11046   11083   +37     
=======================================
+ Hits          8956    8992   +36     
- Misses        2090    2091    +1

🚀 New features to boost your workflow:

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

Borda · 2026-04-27T12:15:27Z

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 · 2026-04-27T12:22:00Z

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

# Conflicts: # tests/cli/test_optional_dependencies.py

socket-security · 2026-05-22T15:36:32Z

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

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/opencv-python-headless@4.13.0.92

View full report

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

+headless = [
+    "opencv-python-headless",          # OpenCV without GUI system libraries for Linux server images
+    "supervision>=0.20.0,<0.21.0",     # TODO: last Supervision line that depends on opencv-python-headless
+]


…dless >=4.8,<5 - Remove supervision>=0.20.0,<0.21.0 from headless extra — conflicted with base supervision==0.29.0rc0 (empty intersection → ResolutionImpossible) - Pin opencv-python-headless>=4.8,<5 for API stability - Resolves DEP-001 (critical) and NIT-004 from /review of PR roboflow#999 --- Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

…rectness fixes - Create src/rfdetr/compat/supervision.py — relocates _attach_detection_metadata, _make_keypoints, _empty_keypoints_is_empty out of detr.py (ARCH-001) - Replace try/except string-match TypeError detection with inspect.signature check via module-level _KEYPOINTS_ACCEPTS_NEW_API flag (CORR-003, PERF-001) - Guard xy.ndim != 3 with ValueError before constructor call (CORR-002) - Add None guard to _attach_detection_metadata, raises ValueError (CORR-006) - Add instance-level comment on is_empty assignment (NIT-001) - Update detr.py to import from rfdetr.compat.supervision --- Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

…ta tests - Fix import: _attach_detection_metadata now from rfdetr.compat.supervision (CORR-005) - Add TestAttachDetectionMetadata class — parametrized (NIT-005) covering: no-metadata creation, existing-key preservation, overwrite, None→ValueError (COV-001) - Add TestMakeKeypoints: new-API path, flag assertion, 2D-xy ValueError, fallback path via monkeypatch (CORR-001), empty-detections is_empty override (CORR-004) - Add TestEmptyKeypointsIsEmpty (NIT-002) --- Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

…requirements - Add CI step: uv pip install --dry-run .[headless] on Linux — catches future dep conflicts before user reports (CI-001) - README: replace vague clean environment with explicit conflict scenario + scope note; confirm detection/seg/keypoints all supported (DOC-001) - AGENTS.md: replace ambiguous clean environment with explicit venv requirement and conflict explanation (DOC-002) - docs/getting-started/install.md: same clean-environment + scope callout (DOC-004) --- Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

robmarkcole · 2026-06-15T08:12:19Z

HI @Borda need anything else from me to get this over the line?

Implemented headless install support

779595b

robmarkcole requested review from Borda, SkalskiP, isaacrob and probicheaux as code owners April 25, 2026 13:14

robmarkcole mentioned this pull request Apr 25, 2026

[DRAFT] Add rfdetr ObjectDetectionTask torchgeo/torchgeo#3625

Draft

Borda requested review from Copilot April 27, 2026 11:19

Copilot started reviewing on behalf of Borda April 27, 2026 11:19 View session

Borda reviewed Apr 27, 2026

View reviewed changes

Comment thread pyproject.toml Outdated

Apply suggestions from code review

3f8bc30

Co-authored-by: Jirka Borovec <6035284+Borda@users.noreply.github.com>

Borda previously approved these changes Apr 27, 2026

View reviewed changes

Merge branch 'develop' into issue-531

1cae48b

Copilot AI reviewed Apr 27, 2026

View reviewed changes

github-actions Bot added the has conflicts label May 15, 2026

Merge remote-tracking branch 'upstream/develop' into issue-531

08a03e7

# Conflicts: # tests/cli/test_optional_dependencies.py

robmarkcole dismissed Borda’s stale review via 08a03e7 May 22, 2026 15:35

github-actions Bot removed the has conflicts label May 22, 2026

Borda added the enhancement New feature or request label May 22, 2026

github-actions Bot added the has conflicts label Jun 10, 2026

Borda force-pushed the develop branch from fb04cf8 to 1a63efe Compare June 12, 2026 15:07

Borda previously approved these changes Jun 13, 2026

View reviewed changes

Merge branch 'develop' into issue-531

22196a6

robmarkcole dismissed Borda’s stale review via 22196a6 June 13, 2026 05:28

github-actions Bot removed the has conflicts label Jun 13, 2026

Borda requested review from Copilot and removed request for Copilot June 13, 2026 09:02

Copilot started reviewing on behalf of Borda June 13, 2026 09:03 View session

Copilot AI reviewed Jun 13, 2026

View reviewed changes

Comment thread pyproject.toml

Comment on lines +50 to +53

headless = [

"opencv-python-headless", # OpenCV without GUI system libraries for Linux server images

"supervision>=0.20.0,<0.21.0", # TODO: last Supervision line that depends on opencv-python-headless

]

Borda and others added 5 commits June 13, 2026 13:34

Merge remote-tracking branch 'origin/develop' into issue-531

ab5a763

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implemented headless install support#999

Implemented headless install support#999
robmarkcole wants to merge 10 commits into
roboflow:developfrom
robmarkcole:issue-531

robmarkcole commented Apr 25, 2026

Uh oh!

CLAassistant commented Apr 25, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

codecov Bot commented Apr 27, 2026 •

edited

Loading

Uh oh!

Borda commented Apr 27, 2026

Uh oh!

robmarkcole commented Apr 27, 2026

Uh oh!

socket-security Bot commented May 22, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

robmarkcole commented Jun 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

robmarkcole commented Apr 25, 2026

What does this PR do?

Type of Change

Testing

Checklist

Additional Context

Uh oh!

CLAassistant commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

codecov Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Borda commented Apr 27, 2026

Uh oh!

robmarkcole commented Apr 27, 2026

Uh oh!

socket-security Bot commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

robmarkcole commented Jun 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

CLAassistant commented Apr 25, 2026 •

edited

Loading

codecov Bot commented Apr 27, 2026 •

edited

Loading

socket-security Bot commented May 22, 2026 •

edited

Loading