geointel/docs/BATHYMETRY_EXPANSION_ROADMAP.md

# Bathymetry expansion roadmap

## Purpose

GeoIntel must distinguish three different questions:

1. Where were cross-sections measured and what does the source document say?
2. What is the continuous elevation of the bed at a specific survey epoch?
3. What is the water depth or volume at a specific moment?

The first question is operational for Flanders through VHA cross-section
profiles. The second is now operational for bounded, surveyed Walloon
waterways through the official SPW raster. A bed model does not provide water
depth without a compatible water-surface elevation. Flood-hazard maximum depth
is a scenario result and must not be reused as current water level.

## Governed source matrix

| Source | Coverage | Data | Vertical reference | GeoIntel status |
| --- | --- | --- | --- | --- |
| VMM VHA Digital Atlas | Flanders | Point locations, structured profile fields, PDF evidence | Document-specific | Operational, bounded vector acquisition |
| MDK Belgian Continental Shelf model | Belgian North Sea | Continuous 20 x 20 m bathymetric raster | LAT | Available, not integrated |
| SPW navigable waterways and reservoir lakes | Wallonia | 0.5 m bed-elevation raster and XYZ cloud | mDNG | Operational, pinned operator archive and bounded COG |
| Port of Antwerp-Bruges publications | Port survey areas | Periodic soundings | Product-specific | Catalog candidate |

VHA contains approximately 129,643 profile points across Flanders at the
observed catalog state. This is a scale indication, not a fixed contractual
count. Mol contained 828 exact in-boundary points during source validation,
715 with document links and 112 with a structured depth field. Production
provisioning always records the live counts and checksums.

## Operational tier 1: Mol

- Query only an explicit EPSG:4326 bbox.
- Intersect the bbox with the exact persisted Mol Area.
- Page the official ArcGIS FeatureServer response without truncation.
- Resolve VHA watercourse names from the official atlas layer.
- Normalize profile points to EPSG:4326.
- Persist the artifact through `DatasetService.import_vector_bytes`.
- Persist every point through `VectorFeatureService`; the provider never
  writes directly to `vector_features`.
- Expose document, measurement date, depth and width fields without parsing or
  inventing values from scanned PDFs.
- Keep volume unsupported.

## Tier 2: all of Flanders

Flanders must be provisioned as exact municipality or other approved Area
partitions, not as one monolithic request. The backend feature limit protects
the provider and the application. A regional logical layer may group complete
partitions, but each Dataset retains its Area id, query URLs, checksums, exact
count and measurement-date range.

Regional activation now uses the complete checksum-bound municipality
manifest. The Map flow chooses the exact Area partition for a municipality and
uses a bounded multi-Dataset PostGIS query for regional rectangles or the
complete Flanders Area. GeoJSON remains limited to 1,000 rendered features;
counts and configured metrics cover the complete spatial result. Individual
profile dates remain authoritative and no Dataset-level survey date is
fabricated.

Remaining operational follow-up:

- add freshness/version probing for the VHA MapServer;
- keep selection-performance evidence as the profile inventory grows;
- retain explicit no-profile municipalities in every refreshed manifest.

## Tier 3: Belgium

Belgian coverage is a federation of source adapters with one normalized
contract, not one assumed national dataset:

- Flanders: VHA profiles and future validated bed rasters;
- Wallonia: SPW bathymetry for measured navigable waterways/reservoirs;
- Brussels: hydrological context until an authoritative public bathymetric
  product is identified;
- federal/maritime: MDK and legally appropriate maritime boundaries.

Every adapter must emit:

- authority and owner;
- exact geographic and temporal coverage;
- horizontal and vertical CRS/datum;
- survey/acquisition time;
- resolution or sample density;
- source URL, request identity, checksum, attribution and license;
- explicit supported and unsupported metrics.

LAT, TAW and mDNG values must never be merged or compared without a documented,
tested vertical transformation and uncertainty statement.

## Tier 4: the Belgian North Sea

The map must distinguish:

- the Belgian land boundary and baseline;
- the territoriale zee (up to 12 nautical miles);
- the Belgian EEZ and continental shelf, which are jurisdictional maritime
  zones and should not be labelled ordinary municipal or provincial
  "grondgebied".

The MDK bathymetry WCS is the preferred continuous source candidate. Activation
requires a live Docker validation of TLS/certificates, GetCapabilities,
coverage identifiers, bounded GeoTIFF retrieval, CRS, LAT, nodata, pixel size,
response limits and maritime clipping. WMTS can support visual context but is
not the analytical source.

## Depth and volume rules

For a compatible bed raster and water-surface raster at the same time and
vertical datum:

`volume_m3 = sum(max(0, water_surface_z - bed_z) * cell_area_m2)`

For surveyed cross-sections along a connected reach:

`volume_m3 = sum(((section_area_i + section_area_i+1) / 2) * reach_length_i)`

The second method requires complete profile geometry, ordered chainage,
contemporaneous water level and defensible interpolation. VHA profile points
alone do not satisfy those prerequisites.

Historical evolution compares only survey epochs with documented compatible
coverage, datum and method. A changed raster footprint is not automatically
bed evolution.

## Implementation order

1. Operate and validate the Mol VHA profile Dataset and map flow. **Done.**
2. Add VHA municipal partition orchestration for Flanders. **Done and live:
   285/285 municipality partitions accounted for, 269 with data, 16 explicit
   no-profile results, 128,913 profile points and zero failures. Regional
   selection and export now aggregate the latest complete manifest in
   PostGIS.**
3. Implement a bounded MDK WCS probe, then acquisition behind live evidence.
   **Probe implemented. Acquisition blocked because the live endpoint fails
   strict hostname validation and does not expose usable capabilities.**
4. Implement SPW download staging and vertical-datum metadata validation.
   **Done: pinned official ZIP, safe `/vsizip/` access, bounded COG,
   DatasetService persistence, map overlay and mDNG selection metrics.**
5. Add maritime boundaries as separate authoritative scope layers.
   **Done for the Belgian territorial sea, EEZ and continental shelf.**
6. Add cross-source vertical-datum transformation only with authoritative
   grids/parameters and uncertainty tests.
7. Add volume only after a compatible measured or modeled water-surface source
   is part of the same analysis contract.

The Flanders scope is land-only and is dynamically derived from the complete
current VRBG municipality collection (285 members at the 2026-07-17
validation). Belgium is not represented by expanding that polygon. Wallonia,
Brussels, the territorial sea and the Belgian EEZ/continental shelf require
their own authoritative adapters and legal scope labels.