geointel/docs/RASTER_OPERATIONS_SPEC.md

GeoIntel Kempen — Raster Operations Specification v1.0

Raster operations are implemented with Rasterio, GDAL-compatible tooling, NumPy and optional OpenCV.

Global requirements

• Never assume band order without metadata or explicit user selection.
• Preserve georeferencing for all derived rasters.
• Use Cloud Optimized GeoTIFF when generating large outputs if practical.
• Store previews separately from analytical rasters.
• Keep nodata values and masks explicit.

Required V1 operations

1. Metadata extraction

Input: raster file.

Output:

{
  "driver": "GTiff",
  "width": 4096,
  "height": 4096,
  "band_count": 4,
  "crs": "EPSG:31370",
  "bounds": [xmin, ymin, xmax, ymax],
  "resolution": [0.25, 0.25],
  "dtype": ["uint8"],
  "nodata": [null],
  "transform": [..]
}

2. Band statistics

For each band:

• min
• max
• mean
• std
• nodata ratio
• histogram bins
• nodata count
• valid pixel count
• dtype
• optional histogram bins approximation

3. Preview generation

Generate browser-friendly previews:

• PNG preview for full raster or overview.
• Optional tile pyramid later.
• Support contrast stretch.

4. Clip by polygon

Input:

• raster dataset
• area polygon

Output:

• clipped GeoTIFF
• metadata
• preview

5. Reproject

Input:

• raster dataset
• target CRS
• target CRS default: EPSG:31370 when not explicitly set in request
• resampling method: nearest, bilinear, cubic

Output:

• reprojected GeoTIFF

Failure behavior:

• if rasterio is unavailable, return dependency-aware error (RASTER_PROCESSING_UNAVAILABLE)
• if source CRS is missing, return invalid CRS error

6. Tile generation for AI

Input:

• raster dataset
• tile size, default 512 (configured in runtime defaults)
• overlap, default 64
• optional area polygon

Output:

{
  "tile_set_id": "uuid",
  "source_dataset_id": "uuid",
  "source_raster_id": "uuid",
  "bounds": [xmin, ymin, xmax, ymax],
  "tile_size": 512,
  "overlap": 64,
  "parameters": {},
  "count": 16,
  "tile_paths": ["storage/tiles/.../tile_0001.tif"],
  "tiles": [
    {
      "path": "storage/tiles/.../tile_0001.tif",
      "pixel_window": [x, y, width, height],
      "bounds": [xmin, ymin, xmax, ymax],
      "transform": []
    }
  ],
  "ai_inference": false,
  "tile_server": null
}

Failure behavior:

• if rasterio is unavailable: dependency-aware error
• if no raster tiles are generated: empty-result failure

7. Index calculations

NDVI

Required inputs:

• red band index
• NIR band index
• output name (optional)
• formula: (nir - red) / (nir + red)
• nodata/NaN handling: invalid pixels and division-by-zero values are written as NaN
• output dtype: float32
• provenance fields:
  • source_dataset_id
  • operation
  • band_mapping
  • formula
  • output_dtype
  • nodata_strategy
  • value_range_note
• failure behavior:
  • band indices must be positive integers
  • band indices must exist in source dataset
  • RASTER_PROCESSING_UNAVAILABLE when rasterio/numpy missing

Formula:

NDVI = (NIR - Red) / (NIR + Red)

NDWI

Required inputs:

• NIR band index
• green band index
• output name (optional)
• formula: (nir - green) / (nir + green)
• same provenance strategy as NDVI

Formula:

NDWI = (NIR - Green) / (NIR + Green)

NDBI

Required inputs:

• SWIR band index
• NIR band index
• output name (optional)
• formula: (swir - nir) / (swir + nir)
• same provenance strategy as NDVI

Formula:

NDBI = (SWIR - NIR) / (SWIR + NIR)

Derived metadata contract:

• operation: one of raster.ndvi, raster.ndwi, raster.ndbi
• source_dataset_id
• band_mapping
• formula
• output_dtype
• nodata_strategy
• value_range_note
• created_at
• output_dataset_id
• path

8. Threshold to mask

Input:

• raster/index
• threshold operator
• threshold value

Output:

• binary mask raster
• optional vector polygons

Storage output policy

Derived rasters go to:

storage/rasters/derived/{project_id}/{dataset_id}/

Tiles go to:

storage/tiles/{project_id}/{dataset_id}/{tile_set_id}/

Previews go to:

storage/previews/{project_id}/{dataset_id}/

API shape

GET /datasets/{id}/raster/metadata
POST /datasets/{id}/raster/clip
POST /datasets/{id}/raster/reproject
POST /datasets/{id}/raster/tile
POST /datasets/{id}/raster/indices/ndvi
POST /datasets/{id}/raster/indices/ndwi
POST /datasets/{id}/raster/indices/ndbi
POST /datasets/{id}/raster/threshold

V1 target

V1 must implement metadata, preview, clip and tile generation. NDVI/NDWI/NDBI are implemented on local raster files with explicit band selection.