feat: Improve RF-DETR with IoU-aware queries, enhanced segmentation, and functional tests

[karthikgogisetty]

✨ Summary of Enhancements

1. IoU-Aware Query Selection & Adaptive Query Allocation

Improves transformer query initialization by:

• Prioritizing higher-IoU spatial locations.
• Dynamically adjusting the number of queries based on feature confidence.

---

2. Enhanced Segmentation Head

Upgraded segmentation module adds:

• Mask quality prediction (better scoring/ranking).
• Dynamic mask refinement using attention over spatial features.

---

3. Advanced Data Augmentations (Experimental)

Includes optional training augmentations:

• Mosaic
• MixUp
• Copy-Paste

These augmentations are utilities only and are not enabled by default.

---

🔧 Wiring Into Existing Components

Opt-in configuration flags added to:

• rfdetr/models/transformer.py
• rfdetr/models/lwdetr.py
• rfdetr/config.py

Defaults ensure no change to existing model behavior.

---

🧪 Functional Tests & CI

Tests

Tests

• IoU-aware query selector (shapes, score outputs)
• Adaptive query allocation (range, consistency)
• Enhanced segmentation head (mask logits + quality score shapes)
• ModelConfig with new flags:
  • use_iou_aware_query
  • adaptive_query_allocation
  • enhanced_segmentation
  • mask_quality_prediction
  • dynamic_mask_refinement

Note: This functional test suite can be extended with additional cases in future PRs if needed.

Files

• functional_testing.py
• .github/workflows/functional-tests.yml

CI

A new GitHub Actions workflow:

• Installs the package with uv pip install .
• Runs uv run python functional_testing.py on PRs and key branches.

---

🔄 Backward Compatibility

All new features are disabled by default:

Feature	Default
use_iou_aware_query	False
adaptive_query_allocation	False
enhanced_segmentation	False
mask_quality_prediction	True
dynamic_mask_refinement	True

Existing checkpoints and training/inference scripts remain unchanged.

---

📝 Documentation Updates

README.md now includes:

Advanced Features (Experimental)

• IoU-aware query selection
• Adaptive query allocation
• Enhanced segmentation head
• Mask quality prediction
• Advanced augmentations (Mosaic, MixUp, Copy-Paste)

Testing and CI

• Instructions for running:

  python functional_testing.py

or

uv pip install .
uv run python functional_testing.py

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

karthik.gogisetty seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[karthikgogisetty]

I have signed the CLA

[isaacrob-roboflow]

Do you have evidence that these changes improve results?