Initial GeoIntel V1 foundation

docs/DETECTION_PIPELINE_SPEC.md

@@ -0,0 +1,165 @@
+# GeoIntel Kempen — Detection Pipeline Specification v1.0
+
+The detection pipeline converts geospatial imagery into georeferenced object detections stored as GIS features.
+
+## Goal
+
+Run object detection on aerial or satellite imagery and export results as map layers and GeoJSON.
+
+## Supported model family
+
+V1 target:
+
+- Ultralytics YOLO detection model.
+
+Later:
+
+- custom PyTorch models
+- OpenMMLab detectors
+
+## Pipeline
+
+```text
+Raster dataset
+↓
+Raster validation
+↓
+Tile generation
+↓
+Model inference per tile
+↓
+Detection postprocessing
+↓
+Pixel coordinates → geospatial coordinates
+↓
+Merge / de-duplicate overlapping detections
+↓
+Store detections in PostGIS
+↓
+Render as map overlay
+↓
+Export as GeoJSON/CSV
+```
+
+## Step 1 — Validation
+
+Check:
+
+- raster exists
+- raster is readable
+- raster has CRS and transform
+- selected bands are valid
+- tile size is valid
+- model file exists or selected model is available
+
+## Step 2 — Tile generation
+
+Parameters:
+
+```yaml
+tile_size_px: 640
+overlap_px: 96
+bands: [1, 2, 3]
+area_id: optional
+```
+
+Every tile must store:
+
+- tile path
+- source pixel window
+- affine transform
+- bounds
+- source dataset id
+
+## Step 3 — Inference
+
+For each tile:
+
+- convert to model input image
+- run YOLO
+- collect boxes, classes, confidence
+
+Raw detection format:
+
+```json
+{
+  "tile_id": "uuid",
+  "class_name": "building",
+  "confidence": 0.91,
+  "bbox_px": [x1, y1, x2, y2]
+}
+```
+
+## Step 4 — Georeferencing
+
+Convert pixel bbox corners using the tile affine transform.
+
+Output geometry:
+
+- polygon footprint of bbox for detection models
+- centroid point optional
+- original pixel bbox kept in metadata
+
+## Step 5 — Merge and de-duplicate
+
+Because tiles overlap, duplicated detections must be removed.
+
+Default method:
+
+- group by class
+- calculate IoU between overlapping geospatial bboxes
+- apply non-maximum suppression by confidence
+- default IoU merge threshold: 0.5
+
+## Step 6 — Storage
+
+Store each detection:
+
+```yaml
+analysis_run_id
+class_name
+confidence
+geometry
+bbox_json
+source_tile_id
+model_name
+model_version
+metadata_json
+```
+
+## Step 7 — Metrics
+
+Calculate:
+
+- detection count by class
+- mean confidence
+- low confidence count
+- confidence histogram
+- detected area by class when polygon geometry is valid
+
+## API
+
+```http
+POST /analysis/object-detection
+GET /analysis/{id}
+GET /analysis/{id}/detections
+POST /analysis/{id}/exports/geojson
+```
+
+## UI
+
+Detection Lab must allow:
+
+- raster selection
+- model selection
+- class selection
+- confidence threshold
+- tile size
+- overlap
+- run detection
+- map overlay visibility
+- QA/QC handoff button
+
+## V1 acceptable model strategy
+
+If no locally trained model exists yet, the system may support a configurable YOLO model path and clearly mark model classes as model-dependent. The code must not fake detections.