geointel/docs/ANALYSIS_SPECIFICATIONS.md

GeoIntel Kempen — Analysis Specifications v1.0

This file defines exact inputs, outputs and formulas for the first implementation of the analysis engine.

Global rules

• All area-based metrics must be calculated in a projected CRS suitable for Belgium/Flanders, preferably EPSG:31370 internally for metric calculations.
• Store geometries consistently and transform only at API/render boundaries when needed.
• All metrics must include unit, input dataset ids, analysis run id and calculation parameters.
• Never let the AI copilot invent metrics. Metrics must come from the analysis engine.

AreaAnalyzer

Input

• Area polygon.

Output metrics

Key	Unit	Formula
area_m2	m²	ST_Area(area.geometry)
area_km2	km²	area_m2 / 1_000_000
perimeter_m	m	ST_Perimeter(area.geometry)
bbox	geometry/json	calculated bounds

BuildingAnalyzer

Input

• Area polygon.
• Building polygons from GRB, OSM, user vector layer, or AI segmentation/detection polygons.

Processing

1. Clip building geometries to area.
2. Remove invalid geometries or repair with make_valid.
3. Calculate per-building clipped area.
4. Aggregate.

Output metrics

Key	Unit	Formula
building_count	count	number of building features intersecting area
building_area_total_m2	m²	sum clipped building area
building_area_total_ha	ha	building_area_total_m2 / 10000
building_coverage_ratio	ratio	building_area_total_m2 / area_m2
building_density_per_km2	count/km²	building_count / area_km2
mean_building_area_m2	m²	building_area_total_m2 / building_count
largest_building_area_m2	m²	max building area

Output layers

• buildings_clipped
• building_centroids
• large_buildings_top_20

RoadAnalyzer

Input

• Area polygon.
• Road line or polygon features.

Output metrics

Key	Unit	Formula
road_length_total_m	m	sum clipped road lengths
road_length_total_km	km	/1000
road_density_km_per_km2	km/km²	road_length_total_km / area_km2
major_road_length_km	km	filtered by road class if available

Output layers

• roads_clipped
• major_roads_clipped

GreenAnalyzer

Input options

• Green polygons from OSM/GRB/landuse.
• NDVI raster threshold result.
• Segmentation polygons classified as vegetation.

Output metrics

Key	Unit	Formula
green_area_total_m2	m²	sum green polygons clipped to area
green_ratio	ratio	green_area_total_m2 / area_m2
green_patch_count	count	number of disjoint green patches
largest_green_patch_m2	m²	max patch area
green_fragmentation_index	index	green_patch_count / max(green_area_total_ha, 0.01)

Interpretation

High fragmentation means green is split into many smaller patches.

WaterAnalyzer

Input

• Water polygons/lines from GRB/OSM.
• NDWI threshold polygons later.

Output metrics

Key	Unit	Formula
water_area_total_m2	m²	sum clipped water polygon area
water_ratio	ratio	water_area_total_m2 / area_m2
watercourse_length_m	m	sum water line length
distance_to_nearest_water_m	m	minimum distance from area centroid to water geometry

RasterAnalyzer

Input

• Raster dataset.
• Optional area polygon.

Output metrics

Per band:

Key	Unit
band_min	band unit
band_max	band unit
band_mean	band unit
band_std	band unit
nodata_ratio	ratio

Required operations

• Read metadata.
• Clip by area.
• Compute statistics.
• Generate preview tile or PNG.

RemoteSensingIndexAnalyzer

NDVI

Formula:

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

Output:

• ndvi_mean
• ndvi_median
• ndvi_low_ratio using threshold configurable, default < 0.2
• ndvi_high_ratio using threshold configurable, default > 0.5
• vectorized high/low vegetation zones later

NDWI

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

NDBI

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

DetectionAnalyzer

Input

• Detection records with class, confidence and geometry.
• Area polygon.

Output metrics

Key	Unit	Formula
detection_count	count	detections within area
detection_count_by_class	json	group by class
mean_confidence	ratio	average confidence
low_confidence_count	count	confidence below threshold
detected_area_m2_by_class	json	sum polygon area where available

ScoreEngine v1

The score engine must be transparent. Every score returns value, inputs, weights and explanation.

Open Space Pressure Score

Default weights:

building_coverage_ratio: 0.35
road_density_normalized: 0.25
green_ratio_inverse: 0.25
urban_growth_normalized: 0.15

Score:

100 * weighted_sum(normalized_factors)

Nature Connectivity Score

Default weights:

green_ratio: 0.35
largest_green_patch_ratio: 0.25
fragmentation_inverse: 0.25
major_road_barrier_inverse: 0.15

Water Resilience Score

Default weights:

green_ratio: 0.30
water_buffer_presence: 0.20
impervious_inverse: 0.30
low_point_risk_inverse: 0.20

V1 may calculate a simplified score without height data by marking height-dependent factors as unavailable.

Metric storage contract

Each metric row must include:

{
  "analysis_run_id": "uuid",
  "key": "building_density_per_km2",
  "value": 123.4,
  "unit": "count/km2",
  "method": "BuildingAnalyzer.v1",
  "inputs": ["dataset_uuid"],
  "parameters": {},
  "quality_flags": []
}