Expose detections_per_img and topk_candidates in config

[vickysharma-prog]

This PR exposes detections_per_img and topk_candidates as configurable parameters so users can adjust them for dense scenes.

Currently, these values are hardcoded to the torchvision defaults (300 / 1000). In very dense imagery (e.g., large bird colonies or dense tree canopies), this limit can truncate valid detections.

Changes

• Added detections_per_img and topk_candidates to config.yaml with current defaults.
• Passed these parameters through Model.create_model() → RetinaNetHub() → torchvision RetinaNet.
• Added tests in test_main.py to verify the parameters are correctly applied to the model.

Backwards Compatibility

Defaults remain unchanged (300 / 1000), so existing workflows are unaffected.

Benchmarks

See issue #1309 for details. On CPU, increasing the limit showed only modest overhead (~3–8%). The sample images in the repo did not reach the 300-detection cap, so I was not able to demonstrate detection differences locally. Happy to test further with denser imagery if available.

Fixes #1309

---

• Used AI tools for guidance
• I understand all submitted code
• I reviewed and validated all AI-generated suggestions

[bw4sz]

I found an image, I was using a different model, but I believe the general bird detector should get close, if not i'll share the checkpoint.

[vickysharma-prog]

Thanks @bw4sz! Testing now will share results shortly.

[vickysharma-prog]

@bw4sz Test results with the shared image:

Setup:

• Image: 4852 × 6464 pixels
• Model: weecology/deepforest-bird (HuggingFace)
• predict_tile: patch_size=400, patch_overlap=0.25

Results:

detections_per_img	Detections	Time
300 (default)	396	~29 min
1000	396	~25 min

This image shows 719 raw predictions per tile, reduced to 396 after NMS — doesn't appear to hit the per-patch limit with this model.
You mentioned using a different model. Would you like me to test with your checkpoint? That might show the limit being hit.

PR #1314 is ready whenever you'd like to review!

[bw4sz]

But didn't you write above that the limit is 300 detections per image?

[vickysharma-prog]

The detections_per_img=300 limit is applied per tile, not to the full image.

Since predict_tile() splits the image into multiple patches (352 in this case), each tile can return up to 300 detections independently. After stitching tiles together and applying NMS across overlaps, the combined count can exceed 300.

In this test, the model produced 719 total raw predictions across all tiles, reduced to 396 after NMS — so individual tiles weren't hitting the 300 cap with this image/model combination.
If you'd like, I can test with your alternate checkpoint to see a case where the limit is hit more clearly. Let me know!

[vickysharma-prog]

@bw4sz Just following up would you like me to test with your checkpoint to demonstrate the limit being hit, or is this ready for review as-is? Happy to resolve conflicts and mark ready whenever.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.98%. Comparing base (f45293f) to head (565ced1).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1314   +/-   ##
=======================================
  Coverage   86.97%   86.98%           
=======================================
  Files          24       24           
  Lines        3009     3011    +2     
=======================================
+ Hits         2617     2619    +2     
  Misses        392      392           

Flag	Coverage Δ
unittests	86.98% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[vickysharma-prog]

@bw4sz Rebased and added detections_per_img and topk_candidates to the config schema all CI checks passing now.

Testing with the shared image didn't hit the per-tile 300 cap. If you'd like, I can test with your alternate checkpoint to demonstrate the limit in a denser scenario.
Ready for review!

[bw4sz]

@jveitchmichaelis drop one of those tree images here.

[vickysharma-prog]

@jveitchmichaelis Hi! Would you mind sharing one of those tree images when you get a chance? Would love to test this out properly. Thanks!