feat: custom image source for YOLOOverlay

[onuralpszr]

🛠️ PR Summary

_{Made with ❤️ by Ultralytics Actions}

🌟 Summary

Adds flexible support for rendering YOLO detections over custom image sources (e.g., HTTP/RTSP, local files) by extending YOLOOverlay with optional image geometry parameters and updating the package version and changelog.

📊 Key Changes

• ✨ Extended YOLOOverlay to support custom image sources in addition to the camera view.
• 🧩 Added optional imageRect and imageSize parameters to YOLOOverlay, with an assertion to ensure they are provided together.
• 🎯 Implemented coordinate transformation logic in both YOLOOverlay and YOLODetectionPainter to map detections from original image space to on-screen positions.
• 🖱️ Updated tap detection logic to respect transformed bounding boxes for accurate hit-testing on custom images.
• 🏷️ Adjusted label drawing to use transformed detection rectangles so labels align with overlays on scaled/positioned images.
• 🌀 Updated shouldRepaint in YOLODetectionPainter to account for imageRect and imageSize changes.
• 📄 Documented the new behavior and example usage in YOLOOverlay docs and added a new 0.1.42 entry to CHANGELOG.md.
• 🔖 Bumped pubspec.yaml version from 0.1.40 to 0.1.42 to publish the new feature.

🎯 Purpose & Impact

• ✅ Enables correct overlay positioning for detections on non-camera image sources (HTTP/RTSP streams, local files, etc.).
• ✅ Fixes cases where bounding boxes and labels appeared outside image bounds when using custom images.
• ✅ Maintains full backward compatibility for existing YOLOOverlay usage without additional parameters.
• ✅ Improves user experience for Flutter apps integrating Ultralytics YOLO models across more diverse image pipelines, especially on iOS.
• ✅ Clarifies usage via in-code documentation and changelog, easing adoption for developers.

[UltralyticsAssistant]

👋 Hello @onuralpszr, thank you for submitting a ultralytics/yolo-flutter-app 🚀 PR to add custom image support for YOLOOverlay on iOS! This is an automated review helper; a human engineer will follow up to assist further.

To ensure a seamless integration of your work, please review the following checklist:

• ✅ Define a Purpose: Clearly explain the purpose of your fix or feature in your PR description (e.g., support for custom image sources and correct overlay positioning) and link to any relevant issues. Ensure your commit messages are clear, concise, and adhere to the project's conventions.
• ✅ Synchronize with Source: Confirm your PR is synchronized with the ultralytics/yolo-flutter-app main branch. If it's behind, update it by clicking the 'Update branch' button or by running git pull and git merge main locally.
• ✅ Ensure CI Checks Pass: Verify all Ultralytics Continuous Integration (CI) checks are passing. If any checks fail, please address the issues.
• ✅ Update Documentation: Update the relevant documentation for any new or modified features, especially describing the new imageRect and imageSize usage in YOLOOverlay.
• ✅ Add Tests: If applicable, include or update tests (or example/demo usage) to cover your changes, and confirm that all tests are passing.
• ✅ Sign the CLA: Please ensure you have signed our Contributor License Agreement if this is your first Ultralytics PR by writing "I have read the CLA Document and I sign the CLA" in a new message.
• ✅ Minimize Changes: Limit your changes to the minimum necessary for your bug fix or feature addition. "It is not daily increase but daily decrease, hack away the unessential. The closer to the source, the less wastage there is." — Bruce Lee

For more guidance, please refer to our Contributing Guide. Don't hesitate to leave a comment if you have any questions. Thank you for contributing to Ultralytics! 🚀

[codecov]

Codecov Report

❌ Patch coverage is 0% with 44 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
lib/widgets/yolo_overlay.dart	0.00%	44 Missing ⚠️

📢 Thoughts on this report? Let us know!

[UltralyticsAssistant]

🔍 PR Review

_{Made with ❤️ by Ultralytics Actions}

Overall the PR is well-structured and keeps the existing API backward compatible while adding flexible support for custom image sources. The coordinate transform and hit-testing logic are consistent between tap handling and painting, and shouldRepaint correctly accounts for the new fields.

Main follow-ups:

• Strengthen the imageRect/imageSize pairing guarantee with a runtime check, not only a debug assert.
• Clarify in the documentation that detection bounding boxes must be in original image coordinates when using custom images and that imageRect must match the displayed image area.
• Consider deduplicating the _transformRect logic between YOLOOverlay and YOLODetectionPainter and optionally precomputing scale factors in the painter for minor performance gains.

💬 Posted 4 inline comments

[UltralyticsAssistant]

🔍 PR Review 2

_{Made with ❤️ by Ultralytics Actions}

Please add a runtime guard so mismatched imageRect/imageSize pairs are rejected outside debug builds, and update YOLODetectionPainter.shouldRepaint to react to content changes instead of only list identity to avoid stale overlays when detection lists are mutated in place.

💬 Posted 2 inline comments

[UltralyticsAssistant]

⚠️ HIGH: oldDelegate.detections != detections compares list identity, so if callers mutate an existing detections list in place (common when reusing buffers) the painter will think nothing changed and skip repainting, leaving stale boxes on screen. Consider comparing contents (e.g., !listEquals(oldDelegate.detections, detections)) or passing an immutable copy so the painter reliably invalidates when detection data changes.

[UltralyticsAssistant]

💡 MEDIUM: assert only runs in debug, so a production build can supply only imageRect or only imageSize and the overlay will silently fall back to the original coordinates, producing badly aligned drawings and tap hit-testing with no signal to the caller. Please replace the debug assert with a runtime guard (e.g., throw an ArgumentError) so invalid input is rejected in release builds as well.