Add operator YOLO label QA contact sheets

2026-07-11 21:34:22 +02:00
parent 8cb435361d
commit fbccf8322e
7 changed files with 682 additions and 0 deletions
@@ -0,0 +1,63 @@
+# YOLO Label QA Contact Sheets Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build an operator-only visual QA script that creates deterministic contact-sheet PNG artifacts from existing YOLO tile datasets.
+
+**Architecture:** Add a standalone script under `scripts/` with no backend/API/database changes. The script reads `yolo_tile_dataset_summary.json`, resolves image and label paths, selects a bounded deterministic tile subset, draws normalized YOLO labels using Pillow, and writes JSON/Markdown/PNG artifacts.
+
+**Tech Stack:** Python standard library, Pillow, pytest subprocess-based script tests.
+
+---
+
+### Task 1: Regression Test
+
+**Files:**
+- Create: `backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py`
+
+- [ ] Write a failing test that creates a tiny YOLO dataset with train/val images, valid labels, an invalid label row and a missing label path.
+- [ ] Run `python -m pytest backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py -q`.
+- [ ] Expected result: failure because `scripts/render_operator_yolo_label_qa_contact_sheets.py` does not exist.
+
+### Task 2: Script Implementation
+
+**Files:**
+- Create: `scripts/render_operator_yolo_label_qa_contact_sheets.py`
+
+- [ ] Implement CLI arguments:
+  - `--summary-path`
+  - `--output-dir`
+  - `--max-tiles`
+  - `--columns`
+  - `--thumb-size`
+- [ ] Implement summary loading and `/app/...` path resolution consistent with existing operator scripts.
+- [ ] Implement YOLO label parsing with invalid/missing counts.
+- [ ] Implement deterministic tile selection.
+- [ ] Implement Pillow rendering to PNG contact sheets.
+- [ ] Implement JSON and Markdown reports.
+- [ ] Run the targeted test and keep the implementation minimal until it passes.
+
+### Task 3: Documentation
+
+**Files:**
+- Modify: `scripts/README.md`
+- Modify: `docs/TODO.md`
+- Modify: `docs/CODEX_EXECUTION_LOG.md`
+
+- [ ] Document the command and intended usage.
+- [ ] Mark visual contact sheets as implemented in TODO.
+- [ ] Record local and Tower validation evidence.
+
+### Task 4: Verification And Deploy
+
+**Commands:**
+- `python -m pytest backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py -q`
+- `python -m pytest backend/tests/test_sprint146_operator_yolo_dataset_quality_audit.py backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py -q`
+- `bash scripts/run_readiness_check.sh`
+- `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/deploy_tower.ps1`
+- Tower script run against `/app/storage/operator-data/yolo-building-aoi1024-cleanpx12vis035/yolo_tile_dataset_summary.json`
+
+- [ ] Commit and push after local readiness.
+- [ ] Redeploy Tower.
+- [ ] Generate Tower contact sheets.
+- [ ] Commit and push evidence docs.