geointel/docs/VECTOR_OPERATIONS_SPEC.md

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:

{
  "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:

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