geointel/docs/SEGMENTATION_PIPELINE_SPEC.md

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

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:

minimum_area_m2: 1.0
simplify_tolerance_m: 0.10

Required segmentation record

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

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.