geointel/docs/superpowers/specs/2026-07-11-yolo-label-qa-contact-sheets-design.md

YOLO Label QA Contact Sheets Design

Goal

Add an operator-only visual QA helper that renders existing YOLO tile images with their YOLO bbox labels overlaid into deterministic contact-sheet PNG artifacts.

Scope

This is not a product feature and does not change API contracts, database schema, model activation, detection inference, provider fetching or training. It only reads an already exported YOLO tile dataset and writes visual evidence artifacts for human inspection before another training run.

Inputs

• yolo_tile_dataset_summary.json from scripts/export_operator_yolo_tile_dataset.py.
• Existing tile image files referenced by the summary.
• Existing YOLO label files referenced by the summary.

Outputs

• operator_yolo_label_qa_summary.json
• operator_yolo_label_qa_contact_sheet.md
• One or more PNG contact sheets under the chosen output directory.

Each selected tile preview shows the image, label boxes and compact metadata: sample slug, split, label count and background category when present.

Selection Strategy

The first implementation should be deterministic and small:

• include tiles with the highest label counts;
• include tiles from low-label positive/context samples;
• include a small number of negative tiles;
• limit total rendered tiles with --max-tiles.

This is enough to catch common issues such as shifted imagery, clipped labels, wrong class files, empty positives and mislabeled background tiles.

Rendering Strategy

Use Pillow, already available in the project runtime. Draw boxes from normalized YOLO labels directly onto the tile image. Invalid or missing label files are reported in JSON/Markdown and skipped for box drawing, not silently ignored.

Error Handling

• Missing summary file: fail with a clear process error.
• Missing image files: record skipped image count and continue if other selected images can be rendered.
• Missing label files: record missing label count and render the image without boxes.
• Invalid label rows: record invalid row count and render only valid boxes.

Tests

Add focused tests that create tiny fixture images and YOLO labels in a temporary dataset directory, run the script and assert:

• JSON and Markdown reports are created;
• contact-sheet PNG exists;
• selected tile count is deterministic;
• invalid labels are counted;
• missing label files are counted;
• rendered output is not blank.

Acceptance

The helper is acceptable when local targeted tests pass, full readiness passes, the all-in-one Tower runtime is redeployed, and the clean AOI1024 dataset emits contact sheets on Tower.