geointel/docs/DETECTION_PIPELINE_SPEC.md

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

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:

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:

{
  "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
• implemented for configured-YOLO as EPSG:4326 cross-tile duplicate suppression before Detection persistence; YOLO_DUPLICATE_IOU_THRESHOLD=0 disables the GeoIntel-side pass for debugging.

Step 6 — Storage

Store each detection:

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

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.