geointel/docs/PYTORCH_MODEL_PROGRAM.md

PyTorch model programme

Principle

PyTorch is the governed CUDA runtime for trainable image models. It is not a replacement for authoritative GIS processing. Terrain, flood depth, land-use classes, road length, water area and vector/raster change remain deterministic source-derived analyses.

Capability matrix

Capability	Method	Current state	Promotion requirement
Building localisation	YOLO detection on orthophoto	Operational for building; validated only in Mol/Kempen	geographically independent Belgian train/validation/test portfolio, including Flanders, Wallonia and Brussels
Building footprint	official GRB/PICC/URBIS geometry	Operational where the governed source covers the AOI	no neural model; source coverage and freshness gates
Roads and water	official vectors and thematic rasters	Operational by provider zone	no detector unless a separately justified imagery use case and reviewed labels exist
Land use / vegetation	official classified rasters	Operational where source coverage exists	no neural model; preserve official class semantics
Terrain / flood / bathymetry	numeric raster analysis	Operational or explicit not_configured per source	no neural model; source and CRS validation
Solar panels or other imagery objects	dedicated detector	Unvalidated local asset only	task-specific labels, negative corpus, independent hold-outs and promotion report
Segmentation	dedicated YOLO-seg/SAM model	not_configured	reviewed polygon/mask corpus and segmentation QA; detection boxes are not valid mask labels

Training rules

1. One model contract per task and canonical class set.
2. Training, validation and test samples are separated geographically; an AOI or overlapping image tile may occur in only one split.
3. Reference labels identify authority, source, layer, observation/publication date, CRS and checksum.
4. Production training requires NVIDIA CUDA and fails closed when unavailable.
5. Every challenger is evaluated on positive AOIs, pure-empty negatives and difficult contextual negatives. Promotion is never based on training loss.
6. A model remains not_configured outside its independently proven geography and classes.

Executable waves

1. Building Belgium corpus: prepare spatially disjoint samples from GRB (Flanders), PICC (Wallonia) and URBIS (Brussels) against temporally compatible orthophotos. Keep complete municipalities outside training as test areas.
2. Building challenger: train on Tower using PyTorch CUDA, compare against the active model at fixed thresholds and retain the current model unless all promotion gates pass.
3. Additional imagery task intake: admit solar panels or another class only after an explicit use case and reviewed labels exist. Never infer new classes from the building corpus.
4. Segmentation intake: build a polygon/mask corpus and independent QA before enabling YOLO-seg or SAM.

The tile exporter accepts explicit --class-name, --reference-source and --reference-layer values and records them in dataset evidence. The production training wrapper supports TRAIN_REQUIRE_CUDA=true and records CUDA and PyTorch runtime evidence in every training summary.