feat(export): QA overlay renderer for exported alert datasets

[Chouffe]

What

Adds annotation_api/scripts/data_transfer/export/render_overlays.py (+ make render-overlays), a QA tool that draws the exported boxes back onto the exported frames so annotation work can be eyeballed against the annotator UI.

It reads a dataset written by make export-alerts (manifest.jsonl + images/) and writes <dataset>/overlays/:

overlays/
├── index.csv                 # kind, alert id, sequence id, camera, org, types, frames, boxes, date, sheet
├── smoke/                    # one contact sheet per smoke object
├── false_positive/           # one per sampled false-positive object
└── multi_object/             # one combined sheet per multi-object alert

Each sheet lays an object's frames out in time order. A cell stacks the full frame with its boxes drawn, a magnified crop of the box region, and a caption naming the detection id. The crop row is what makes the sheets usable: exported boxes are typically ~0.05% of frame area, invisible once a 1280x720 frame is scaled into a grid cell.

For a multi-object alert every lane draws on the same image in its own colour, and each lane gets its own zoom panel — a crop around the union of two objects at opposite ends of the frame just reproduces the frame. Sibling lanes hold their own copies of a capture (distinct detection ids, usually distinct bucket_keys), so frames are aligned across lanes by exact recorded_at.

Why

Verifying an export numerically (counts, xyxyn bounds, file presence) says nothing about whether a box actually sits on the plume. This makes that check cheap and repeatable, and the sheet filenames carry the UI's own identifiers (alert{platform_alert_id}_seq{sequence_id}_{camera}.png) so a reviewer can jump straight to the matching lane.

Usage

make render-overlays DATASET_DIR=outputs/alerts_export [FP_SAMPLE=40]

# or directly, for finer control
uv run python -m scripts.data_transfer.export.render_overlays \
  --dataset-dir outputs/alerts_export --mode objects|multi|both \
  --fp-sample 40 --alerts 52124 57057

Every smoke lane is rendered, plus FP_SAMPLE false-positive lanes chosen round-robin across false-positive type combinations so the sample spans all of them before deepening any one. FP_SAMPLE caps only the per-object sheets — the multi-object pass covers every multi-lane alert; --alerts is what bounds a run.

Robustness

The renderer never assumes an image is there or readable. A capture is drawn from whichever lane's copy actually decodes, so on a multi-object alert a sibling rescues a capture the first lane lost. Two failure modes it tolerates, both reachable from a real export:

• image_path: null — what export_alerts.py writes for a download it could not complete.
• a present but truncated/0-byte .jpg — never re-downloaded, since the exporter's idempotency check is mere file existence.

Unrenderable captures are skipped with a warning, an alert with no usable image yields no sheet, and index.csv lists only sheets that were actually written.

Verification

• Ran against a real 767-alert / 17,502-image export from the test server: 92 sheets (35 smoke, 40 false-positive, 17 multi-object), boxes land on the annotated objects in every sheet inspected.
• Broken-dataset test covering null paths, a deleted file, a 0-byte file, and an alert with no usable image at all: exit 0, no crash, and index.csv matches the PNGs on disk exactly.
• uv run ruff check . (what the Ruff CI job runs), ruff format --check, and mypy all clean.

No application code is touched — this is scripts, Makefile and docs only.