Initial public release

docs/VECTOR_OPERATIONS_SPEC.md

@@ -0,0 +1,162 @@
+# GeoIntel Kempen — Vector Operations Specification v1.0
+
+Vector operations are implemented with GeoPandas/Shapely in the backend and optionally accelerated through PostGIS.
+
+## Global requirements
+
+- Always validate CRS before spatial operations.
+- Use metric CRS for area, length and distance calculations.
+- Repair invalid geometries before operations.
+- Return operation metadata with input dataset ids and parameters.
+- Persist important outputs as derived layers.
+
+## Required V1 operations
+
+## 1. Metadata extraction
+
+Input: vector dataset.
+
+Output:
+
+```json
+{
+  "feature_count": 1234,
+  "geometry_types": ["Polygon"],
+  "crs": "EPSG:31370",
+  "bounds": [xmin, ymin, xmax, ymax],
+  "columns": [{"name":"type","dtype":"str"}]
+}
+```
+
+## 2. Reproject
+
+Input:
+
+- vector dataset
+- target CRS
+
+Output:
+
+- reprojected layer
+- operation log
+
+## 3. Clip
+
+Input:
+
+- vector dataset
+- area polygon
+
+Output:
+
+- clipped layer
+- metrics: before/after feature count, retained area/length
+
+## 4. Buffer
+
+Input:
+
+- vector dataset
+- distance in meters
+- dissolve boolean
+
+Output:
+
+- buffer polygon layer
+
+## 5. Intersect
+
+Input:
+
+- layer A
+- layer B
+
+Output:
+
+- intersection layer
+- area/length metrics
+
+## 6. Difference
+
+Input:
+
+- layer A
+- layer B
+
+Output:
+
+- geometries in A not covered by B
+
+Use case: changed features, missing reference coverage.
+
+## 7. Spatial join
+
+Input:
+
+- target layer
+- join layer
+- predicate: intersects, within, contains, nearest
+
+Output:
+
+- joined attributes
+- match count
+
+## 8. Dissolve
+
+Input:
+
+- vector layer
+- optional group field
+
+Output:
+
+- dissolved geometries
+
+Use case: combine green patches, merge detection masks.
+
+## 9. Polygonize from raster mask
+
+Input:
+
+- binary or class raster mask
+
+Output:
+
+- polygon layer with class values
+
+This is technically raster-to-vector but must produce vector layers compatible with all vector operations.
+
+## API shape
+
+Vector operations should be available as jobs:
+
+```http
+POST /vector/operations/clip
+POST /vector/operations/buffer
+POST /vector/operations/intersect
+POST /vector/operations/difference
+POST /vector/operations/spatial-join
+POST /vector/operations/dissolve
+```
+
+Each returns a job id and later a derived dataset/layer id.
+
+## Error handling
+
+Return clear validation errors for:
+
+- missing CRS
+- unsupported geometry type
+- invalid geometry repair failure
+- empty output after clipping
+- projection failure
+
+## Test fixtures
+
+Create small fixture GeoJSON files for:
+
+- building polygons
+- road lines
+- area polygon
+- reference/prediction polygons for QA