project/docs/decisions.md

Project decisions

• Use a bounded DOTA RGB detection subset and a region-balanced OpenEarthMap segmentation subset.
• Keep academic-only sources explicit; loader default remains commercially compatible.
• Keep ontology classes without reliable labels at zero coverage rather than synthesizing annotations.
• Visual review records identify all preview sheets and bind to the audited corpus content hash.
• For the model build, use separate YOLO26n-obb and YOLO26n-sem pretrained components unless measured baselines disprove the fit; expose only corpus-supported canonical classes.
• Keep model dependencies separate from the dataset-preparation lockfile. Current host is CPU-only; default local gates and training are explicitly time-bounded, with approval required before switching compute.
• Fixed evaluation uses 32 detection plus 20 segmentation validation tiles; the remaining 68/21 tiles are selection-validation only. Records are disjoint, not scenes; all six segmentation validation regions and 24 detection scenes appear in quick evaluation.
• Detection metrics require a shared coordinate frame: corpus positive obb_polygon is source-image coordinates, but ignored clipped_polygon is tile-local. Translate one side using tile_coordinates before evaluation; preserve oriented geometry.
• Threshold calibration checks detection sample IDs against the fixed manifest, not just caller-provided provenance strings. Segmentation class 15 has only one validation tile, reserved for quick evaluation, so no reliable selection-validation threshold is available.
• Loader approval permits CRLF/LF equivalence only for JSON/JSONL; image/mask bytes and missing approved hashes remain strict.
• DOTA v1.5 annotations retain 16 source categories, not 15. Map pretrained source classes by name and expose only the six supported canonical detection classes.
• Include the only validation segmentation tile with bare-ground pixels (canonical ID 15) in fixed quick evaluation; report the sparse evidence explicitly.
• Keep model library settings in the worktree via YOLO_CONFIG_DIR and select CPUExecutionProvider explicitly for ONNX inference.
• Task 3 official checkpoints are pinned to Ultralytics assets v8.4.0 and SHA-256 in training/model_factory.py; Ultralytics 8.4.185 supports task semantic, not instance-mask segment.
• Official DOTA checkpoint labels contain spaces (for example small vehicle); normalize spelling to DOTA hyphens before name-based transfer. Its 15 classes lack only container-crane from the 16-class private target. Fresh initialization/row transfer belongs only to later adapted models, never the pretrained baseline.
• ADE baseline uses only exact building, road, and water aliases. IDs 13–16 remain unavailable; do not label three-alias mIoU as a seven-class result or invent broad land-cover aliases from tree, field, earth, or land.
• Keep AP on the confidence >=0.001/max_det=300 prediction pool, separate from selection-calibrated operating metrics. Geometry caching is evaluation-local and preserves oriented matching and ignored regions.
• The baseline CLI supervises a spawned worker with a hard 300-second limit including model loading; in-process callers receive cooperative budget checks. Raw detector outputs and compressed original ADE class maps are retained alongside 16 comparable previews and their hashes.