Initial public release

docs/SEGMENTATION_PIPELINE_SPEC.md

@@ -0,0 +1,126 @@
+# 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.