# GeoIntel Kempen — Segmentation Pipeline Specification v1.0

The segmentation pipeline converts raster imagery into georeferenced masks and polygons.

## Goal

Produce class masks for buildings, vegetation, water, or other targets and convert those masks to GIS layers.

## Model families

V1/early:

- YOLO segmentation model if available.
- Segment Anything for prompt-based or automatic masks.

Later:

- U-Net
- DeepLab
- custom PyTorch semantic segmentation

## Pipeline

```text
Raster dataset
↓
Raster validation
↓
Tile generation
↓
Segmentation inference
↓
Mask stitching
↓
Georeferenced mask output
↓
Polygonization
↓
Geometry cleanup
↓
PostGIS storage
↓
Map overlay + statistics
```

## Mask types

### Instance segmentation

Each object has its own mask.

### Semantic segmentation

Each pixel has a class value.

V1 may support instance segmentation first.

## Output storage

- Raw mask files: `storage/masks/{project_id}/{analysis_run_id}/`
- Polygonized outputs in PostGIS `segmentations` table.
- Derived vector layer for map rendering.

## Polygonization rules

1. Convert binary/class mask to shapes using raster transform.
2. Discard polygons below minimum area threshold.
3. Repair geometries.
4. Simplify for display only, keep analysis geometry if possible.
5. Calculate area.

Default thresholds:

```yaml
minimum_area_m2: 1.0
simplify_tolerance_m: 0.10
```

## Required segmentation record

```yaml
analysis_run_id
class_name
geometry
area_m2
confidence
raster_mask_path
source_tile_id
model_name
metadata_json
```

## Metrics

- total segmented area by class
- polygon count by class
- mean confidence by class
- largest polygon by class
- area ratio against selected area

## API

```http
POST /analysis/segmentation
GET /analysis/{id}/segmentations
POST /analysis/{id}/polygonize
POST /analysis/{id}/exports/masks
POST /analysis/{id}/exports/geojson
```

## UI

Segmentation Lab must show:

- raster selector
- model selector
- segmentation mode
- class list
- threshold controls
- mask preview
- polygon overlay
- export buttons

## V1 target

Implement the data structures, job pipeline contracts, mask storage, polygonization utilities and UI shell. Full SAM integration can follow after raster/detection foundation is stable.