geointel/docs/13-implementation-traps/GEOSPATIAL_CALCULATION_RULES.md

Geospatial Calculation Rules

These rules define how GeoIntel must handle geospatial calculations.

Coordinate Reference Systems

Default display CRS: EPSG:4326.

Default metric calculation CRS for Flanders/Kempen: EPSG:31370.

Every dataset must store:

• source CRS
• normalized/display CRS if converted
• metric calculation CRS used for area/distance outputs

Geometry Validation

Before inserting vector features:

1. check geometry exists
2. check geometry type
3. check validity
4. check empty geometry
5. compute bounds
6. compute source feature count

Invalid geometries should be recorded in dataset metadata. Auto-fix may be attempted using buffer(0) or make_valid only if the metadata records this correction.

Area Calculation

Area values must include units.

Preferred units:

• m2 for feature-level area
• ha for summary land cover areas
• km2 for large area summaries

Never calculate area from EPSG:4326 degrees.

Distance Calculation

Distance values must include units.

Preferred units:

• m for local distances
• km for totals and densities

Density Calculation

Densities must define denominator:

• buildings per km2
• road km per km2
• vegetation ha per km2

IoU Calculation

For polygons A and B:

IoU = area(intersection(A, B)) / area(union(A, B))

Both geometries must be projected to metric CRS before area calculation.

Matching Rule

Default object matching threshold for building QA/QC:

IoU >= 0.5

Alternative thresholds may be exposed in UI but must default to 0.5 for first V1 implementation.

Precision, Recall and F1

• TP: predicted feature matched to one reference feature above threshold
• FP: predicted feature without reference match
• FN: reference feature without predicted match

precision = TP / (TP + FP)

recall = TP / (TP + FN)

f1 = 2 * precision * recall / (precision + recall)

If denominator is zero, return null and include explanatory reason.