docs: add Before/After Detection Diff cookbook

[adawgwats]

Description

This PR adds a new cookbook, Before/After Detection Diff (docs/notebooks/before-after-detection-diff.ipynb), and registers its card in docs/theme/cookbooks.html.

The cookbook answers a question none of the existing cookbooks cover: given two photos of the same scene taken at different times, which objects were removed, which persisted, and which are new? The walkthrough narrative is verifying a litter cleanup from a before/after photo pair — the workflow behind cleanup-verification features in field apps — and the closing notes generalize the recipe to shelf audits, equipment inspections, and parking surveys.

What the notebook demonstrates, using public supervision APIs only (zero library changes):

• RF-DETR -> sv.Detections — rfdetr's predict returns supervision's container directly; no from_* conversion.
• sv.InferenceSlicer on 3648x2736 photos — small litter vanishes at DETR input resolution; tiled inference recovers it (11 objects vs 2 without slicing on the demo pair). Cross-links the SAHI cookbook.
• Appearance embeddings — sv.crop_image per detection, ResNet18 with the classifier head dropped, L2-normalized 512-d vectors.
• Hungarian matching — cost matrix blending appearance (0.6), normalized center distance (0.4), and a soft class-mismatch penalty (0.15); scipy.optimize.linear_sum_assignment; matches costing > 0.75 rejected.
• Removed / persisted / new classification, color-coded BoxAnnotator + LabelAnnotator overlays, a pandas summary table, and a conservative verdict rule (verified only when the before photo had >= 1 detection and >= 1 went missing).
• An honest treatment of COCO-checkpoint limits (a bush detected as sheep still matches itself across the pair — matching doesn't need the label to be right) and where a fine-tuned RF-DETR checkpoint and a re-ID embedding slot in.

Demo images

The default pair is the original 2007 Saint-Mandrier-sur-Mer beach cleanup (the pair that later inspired #trashtag), photographed by Stephane Belgrand Rousson and published on Wikimedia Commons by User:Aeroceanaute under CC BY-SA 4.0:

• Before: https://commons.wikimedia.org/wiki/File:Trashtag_2007_Saint_Mandrier_France_Dirty_Stephane_Belgrand_Rousson.jpg
• After: https://commons.wikimedia.org/wiki/File:Trashtag_2007_Saint_Mandrier_France_Clean_by_Stephane_Belgrand_Rousson.jpg

License and authorship are credited in the notebook's markdown. URLs are the stable upload.wikimedia.org originals and were verified to fetch.

Result preview

On the demo pair the diff finds 11 objects before (bottles, cups, the blue crate, moored boats, one mislabeled bush) and 1 after; 1 persists (the bush, matched at cost 0.36), 10 come back removed, 0 new — verdict: cleanup VERIFIED.

Checklist (cookbook guidelines, CONTRIBUTING.md)

• New notebook in docs/notebooks/
• Card added to docs/theme/cookbooks.html (path, title, labels, author, supervision version)
• Structure follows the most recent merged cookbooks (Colab badge at top, ## Install required packages header, pinned supervision>=0.29.0)
• Self-contained: all data downloaded in-notebook, licenses documented, all installs in the first code cell
• Code annotated with links to the docs of each tool used (InferenceSlicer, crop_image, annotators, linear_sum_assignment)
• Executed end to end; outputs committed in the notebook

How it was tested

Executed top to bottom (fresh kernel) on Python 3.9 / supervision 0.29.1 / torch 2.8.0 CPU (Apple Silicon): both images fetch, tiled detection runs in ~10 s total, matching and verdict cells reproduce the numbers above, nbformat.validate passes.

---

Related: #2476 (the match_detections() proposal). This cookbook is docs-only and does not depend on that issue landing — it hand-rolls the assignment step with scipy, which is exactly the duplication the proposal is about.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88%. Comparing base (fb22686) to head (1e2a9c6).

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2477   +/-   ##
=======================================
- Coverage       88%     88%   -0%     
=======================================
  Files           85      85           
  Lines        12042   12042           
=======================================
- Hits         10543   10540    -3     
- Misses        1499    1502    +3     

🚀 New features to boost your workflow:

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