# 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
- 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:

```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.