Afwateringseenheden

De functionele uitleg staat bij Afwateringseenheden. Zie Afwateringseenheden produceren voor de uitvoering, parallel rekenen en logbestanden.

Dekking en hergebruik

Bronextents worden in het geheugen gecachet op basis van bestandsversie, sidecarversies en doel-CRS en op het gevraagde doelgrid gerasteriseerd. Bij overwrite=False worden geldige rasterparen met de actuele coverage-tag source_extents_v2 hergebruikt. Ontbrekende of oudere tags leiden tot regeneratie.

Met landsgrens_path wordt de grenslaag zo nodig naar het raster-CRS omgezet en per worker gecachet. Bij een gewijzigde landsgrensbron (pad, wijzigingstijd of bestandsgrootte) worden bestaande rasters en tegelresultaten opnieuw berekend, ook bij overwrite=False. De functies downloaden de grenslaag zelf niet. Zonder landsgrens_path geldt de dekking van de volledige bronextents. De landsgrenstag bevat ook de maskeringsversie. Uitvoer met de oude maskering, die een raaklijn ten onrechte als DEM-dekking kon opnemen, wordt eenmalig opnieuw berekend. Uitvoer zonder landsgrensmasker blijft herbruikbaar.

Voor hergebruik van tegeluitvoer is ook subcatchments.tif nodig: dit bepaalt de werkelijke buffer; CRS en resolutie moeten overeenkomen. Het opgegeven samengevoegde eindbestand wordt na succes wel vervangen. Kies een nieuw eindpad om de vorige versie te bewaren.

Tegelresultaten

gap_additions bevat aanvullingen uit buurtegels en remaining_gaps de resterende gaten. boundary_issue_tile_ids betreft randproblemen voordat het resultaat is aangevuld. calculation_duration_seconds geeft de verwerkingstijd per tegel, zonder wachttijd in de pool of het gezamenlijke samenvoegen.

skipped_tile_ids bevat tegels zonder segmentcellen op geldige DEM-hoogtes. Hiervoor worden zowel het segmentraster als het NoData-masker en de eindige hoogtewaarden van het DEM gecontroleerd. Voor overgeslagen tegels worden geen LDD- of subcatchmentbestanden gemaakt; de voorbereide rasters blijven behouden.

tiles.gpkg wordt in de opgegeven output_dir geschreven. De laag tiles bevat de geselecteerde kerntiles en een tile_id-kolom met de namen van de bijbehorende tegelmappen.

De functie gebruikt standaard een worker. Parallelle berekeningen gebruiken afzonderlijke spawn-processen en vereisen een script met een __main__-guard.

Tools for preparing vector input for afwateringseenheden.

AfwateringseenhedenTileResult dataclass

Result for one afwateringseenheden tile calculation.

calculation_duration_seconds measures elapsed tile processing time, including reuse checks, but excluding pool queue time. Direct construction without calculation_buffer_m assumes no buffer.

AfwateringseenhedenTilesResult dataclass

Results and merged output from a tiled afwateringseenheden workflow.

SubcatchmentResult dataclass

Files and polygons produced by one subcatchment calculation.

WatersysteemRasters dataclass

Paths to the aligned rasters prepared for one spatial square.

WatersysteemResult dataclass

Prepared primary hydroobject segments and point-induced connections.

hydroobject_segmenten contains primary source lines split at internal point locations and subsequently, by the workflow, at the requested maximum length. hydroobject_verbinding contains a directed, minimal connection tree between final segment_id values at each hydrological node. A segment ending at a node is van_segment and a segment starting there is naar_segment. At a node with multiple incoming and outgoing segments, the lexicographically first segment of each direction is the deterministic main route. Connection geometries are always two-dimensional Points at a shared segment endpoint or at the puntobject that connects endpoints of distinct source hydroobjects.

calculate_afwateringseenheden_tiles(gebied, *, burn_depth_m, ahn_vrt_path=None, landsgrens_path=None, watersysteem_path=None, output_dir=None, merged_output_path=None, tiles_path=None, data_store=None, tile_ids=None, tile_size_m=5000, tile_buffer_m=2000, origin_x=0, origin_y=0, resolution_m=2.0, max_fill_depth_m=50.0, overwrite=False, engine='pcraster', workers=1, clip_to_area=True, random_seed=None)

Calculate afwateringseenheden for every tile intersecting an area.

Parameters:

Name	Type	Description	Default
gebied	BaseGeometry	Project-CRS input selection. Output is clipped only when clip_to_area is True.	required
clip_to_area	bool	Clip merged results to the input area, default True for API compatibility. Production workflows set False to retain complete tile cores.	True
burn_depth_m	float	Burn depth passed to :func:prepare_watersysteem_rasters.	required
ahn_vrt_path	Path	AHN VRT used for every tile. Defaults to the datastore AHN DTM VRT.	None
landsgrens_path	Path	Bestuurlijke gebieden GeoPackage with Dutch landgebied polygons. Limits DEM interpolation and valid elevations to Nederland, including tile buffers. None retains full source-extent coverage. No download is performed. Changed boundary sources invalidate cached tile results.	None
watersysteem_path	Path	Prepared watersysteem GeoPackage. Defaults to the datastore output.	None
output_dir	Path	Root directory for per-tile folders. Defaults to datastore.afwateringseenheden_path / 'tiles'. The selected core tiles are written to tiles.gpkg in this directory. Its tile_id values match the per-tile folder names.	None
merged_output_path	Path	GeoPackage path for the dissolved merged result. When omitted, no merged GeoPackage is written. An existing merged file is replaced after success, independently of overwrite; choose a new path to retain previous merged results. Worker failures prevent merging.	None
tiles_path	Path	Existing tile-index GeoPackage. When omitted, a tile grid is generated directly from gebied using tile_size_m and the configured origin.	None
data_store	DataStore	Datastore used for default input and output paths.	None
tile_ids	Collection[str]	Optional subset of selected tile IDs.	None
tile_size_m	int	Tile width and height in metres, by default 5000.	5000
tile_buffer_m	float	Buffer around each tile used for the hydrological calculation, by default 2000. Boundary issues are reported without recalculating the tile.	2000
origin_x	int	Origin of the generated tile grid, by default 0, 0.	0
origin_y	int	Origin of the generated tile grid, by default 0, 0.	0
resolution_m	float	Raster resolution passed to :func:prepare_watersysteem_rasters.	2.0
max_fill_depth_m	float	Maximum PCRaster depression fill depth in metres.	50.0
overwrite	bool	Whether to regenerate existing per-tile rasters and subcatchments. Cached raster metadata determines the actual buffer. Cached CRS and resolution must match the requested grid. Reusing a tile requires its subcatchments.tif alongside the GeoPackage.	False
engine	pcraster	Flow-direction engine.	"pcraster"
workers	int	Number of separate worker processes. The default of 1 runs serially. Workers open their own inputs and write only to their tile folder, including a workflow.log. Results are merged in selection order. Run parallel workflows from a script with a __main__ guard.	1
random_seed	int	Positive PCRaster seed reset before each fresh tile calculation. Use the same seed for reproducible serial and parallel runs. The default leaves PCRaster's random state unchanged; cached results are reused independently of this setting when overwrite=False.	None

Returns:

Type	Description
AfwateringseenhedenTilesResult	Per-tile results, skipped tile IDs, boundary issue tile IDs, and the in-memory merged GeoDataFrame.

Notes

Tiles without hydroobject-segment cells on valid DEM elevations are skipped, including tiles whose segments lie entirely outside the source coverage or the supplied national boundary. Prepared rasters can still be reused. Line and point remnants from clipping are removed. After merging the core results, uncovered parts of selected tiles are filled from usable neighbour buffer polygons. Polygons touching their calculation boundary are excluded. Donors are ranked by coverage, distance from their outer boundary, and tile ID. Existing assignments are retained. This step performs no new LDD work. gap_additions and remaining_gaps report the changes and unfilled area in memory. Only the merged subcatchments are written to the GeoPackage. Boundary issue tile IDs still describe the original calculations, not the remaining gaps.

calculate_subcatchments(rasters, *, watersysteem_path=None, data_store=None, max_fill_depth_m=50.0, engine='pcraster')

Calculate subcatchments that drain to prepared hydroobject segments.

Parameters:

Name	Type	Description	Default
rasters	WatersysteemRasters	Aligned DEM and hydroobject-segment raster outputs.	required
watersysteem_path	Path	GeoPackage containing hydroobject_segment.	None
data_store	DataStore	Datastore used for the default watersysteem path.	None
max_fill_depth_m	float	Maximum depression fill depth in metres, by default 50.	50.0
engine	pcraster	Flow-direction engine. Only PCRaster is implemented.	"pcraster"

Returns:

Type	Description
SubcatchmentResult	LDD, subcatchment and GeoPackage output paths plus the polygons.

prepare_watersysteem(hydroobjecten, puntobjecten, *, tolerance=2.0, max_length=500.0, hydroobject_secundair=None)

Prepare primary hydroobjecten and final segment connections.

This function only performs geometric and topological preparation. It does not read a GeoPackage, download source data, or write output. Input CRS values are required and are explicitly transformed to settings.crs by the underlying geometry helpers. Hydroobjecten are split first at nearby pointobjects and then into segments no longer than max_length.

Parameters:

Name	Type	Description	Default
hydroobjecten	GeoDataFrame	Primary HyDAMO LineString or MultiLineString features. A missing bron_id is safely derived from globalid, code, or index.	required
puntobjecten	GeoDataFrame	Point features that may split or connect primary hydroobjecten. Relevant point fields are retained on resulting connection records where a point causes a cross-source connection.	required
tolerance	float	Maximum point-to-line distance in project-CRS units. Must be at least zero.	2.0
max_length	float	Maximum resulting hydroobject segment length in project-CRS units. Must be greater than zero.	500.0
hydroobject_secundair	GeoDataFrame	Retained for backwards compatibility. Secondary objects are classified from their full geometry while writing and are not included in primary segment connections.	None

Returns:

Type	Description
WatersysteemResult	hydroobject_segmenten contains stable bron_id and segment_id values. hydroobject_verbinding contains deterministic directed relations between final segment IDs, their source bron_id values, and relevant point attributes.

prepare_watersysteem_rasters(ruimtelijk_vierkant, *, burn_depth_m, ahn_vrt_path=None, landsgrens_path=None, watersysteem_path=None, output_dir=None, data_store=None, resolution_m=2.0, overwrite=False)

Create aligned DEM and hydroobject-segment rasters for one spatial square.

The AHN dtm_05 VRT is resampled to a 2 by 2 metre grid by default. Missing elevation cells inside cached full source raster extents are filled with rasterio.fill.fillnodata using the original full-grid search distance. NoData outside all source extents is not offered for interpolation. With landsgrens_path, source extents are limited to the national boundary. All NoData inside that coverage remains fillable, including at its edges. Gaps left by the masked interpolation use the nearest original finite elevation within coverage. Existing valid outputs are still reused. Outside cells are NoData and cannot be interpolation targets or donors. Primary and secondary hydroobjects are rasterized separately. The primary mask has priority, so its two-times burn depth is not added to the one-times secondary depth in overlapping cells. The companion segment raster stores GeoPackage feature IDs, with zero denoting no segment.

Parameters:

Name	Type	Description	Default
ruimtelijk_vierkant	BaseGeometry	Square output extent in :data:waterlagen.settings.settings.crs. Its width and height must be equal and exactly divisible by resolution_m.	required
burn_depth_m	float	Physical burn depth in metres. Primary hydroobjects are lowered by two times this value and secondary hydroobjects by one times this value.	required
ahn_vrt_path	Path	AHN source VRT. Defaults to datastore.ahn_dir / 'dtm_05' / 'dtm_05.vrt'.	None
watersysteem_path	Path	GeoPackage containing hydroobject_primair, hydroobject_secundair, and hydroobject_segment. Defaults to datastore.afwateringseenheden_path / 'watersysteem.gpkg'.	None
landsgrens_path	Path	Bestuurlijke gebieden GeoPackage with the Dutch landgebied layer. Reprojected to the target CRS; pixel centres determine inclusion. No download is performed. None retains full source-extent coverage.	None
output_dir	Path	Directory for dem_2m.tif and hydroobject_segment.tif. Defaults to datastore.afwateringseenheden_path / 'rasters'.	None
data_store	DataStore	Datastore used for all default paths.	None
resolution_m	float	Cell size in project-CRS metres, by default 2.	2.0
overwrite	bool	Whether existing validated raster pairs are regenerated. With False, both existing valid outputs from this coverage policy are reused. Outputs with missing or outdated coverage metadata or a changed landsgrens source (path, modification time or size) or masking policy are regenerated.	False

Returns:

Type	Description
WatersysteemRasters	Paths to the validated DEM and hydroobject-segment GeoTIFFs.

Side Effects

Writes both GeoTIFFs through temporary files beside their targets. Each completed temporary raster is validated before it atomically replaces its corresponding target.

read_hydroobjecten(hydamo_path, *, spatial_selection=None, waterbeheercodes=None, attribute_filters=None, spatial_selection_crs=settings.crs)

Read selected HyDAMO hydroobjecten as project-CRS line features.

MultiLineStrings are exploded while preserving relevant source attributes. Their parts receive a deterministic :0001-style suffix on bron_id so every returned line can be handled independently. Empty, invalid, and non-line geometries are skipped with a warning. Other returned features use globalid for bron_id where available, otherwise code or the source row index.

Parameters:

Name	Type	Description	Default
hydamo_path	Path	Local HyDAMO GeoPackage containing the hydroobject layer.	required
spatial_selection	BaseGeometry	Selection geometry in spatial_selection_crs. None reads the complete source layer.	None
waterbeheercodes	Iterable[str | int | float | None]	Optional codes parsed from the source nen3610id field.	None
attribute_filters	Mapping[str, Collection[object]]	Exact source-value filters. The documented alias categorieoppervlaktewater maps to the actual HyDAMO column categorieoppwaterlichaam.	None
spatial_selection_crs	str | int	CRS of spatial_selection. Results always use settings.crs.	crs

Returns:

Type	Description
GeoDataFrame	Selected LineString features with source attributes, bron_id, and normalized waterbeheercode in the configured project CRS.

read_puntobjecten(hydamo_path, *, layers=('gemaal', 'stuw'), spatial_selection=None, waterbeheercodes=None, attribute_filters=None, spatial_selection_crs=settings.crs)

Read selected HyDAMO point layers and combine them into one GeoDataFrame.

Every retained point has an objecttype containing its source-layer name and a stable bron_id. Empty, invalid, and non-point geometries are skipped with warnings. All source layers are converted to settings.crs before combining them.

Parameters:

Name	Type	Description	Default
hydamo_path	Path	Local HyDAMO GeoPackage containing the requested point layers.	required
layers	Iterable[str]	Source layer names. Defaults to gemaal and stuw.	('gemaal', 'stuw')
spatial_selection	BaseGeometry	Selection geometry in spatial_selection_crs. None reads each complete source layer.	None
waterbeheercodes	Iterable[str | int | float | None]	Optional codes parsed from source nen3610id fields.	None
attribute_filters	Mapping[str, Collection[object]]	Exact source-value filters with the documented source-column aliases.	None
spatial_selection_crs	str | int	CRS of spatial_selection. Results always use settings.crs.	crs

Returns:

Type	Description
GeoDataFrame	Combined point features with objecttype, bron_id, relevant source fields, and normalized waterbeheercode.

require_pcraster()

Import PCRaster or raise an actionable installation error.

split_connected_secondary_hydroobjecten(hydroobject_secundair, hydroobject_primair, hydroobject_verbinding, *, tolerance=2.0)

Split secondary hydroobjecten into connected and unconnected sources.

Secondary hydroobjecten form spatially connected components. A component is connected only when at least one member lies within tolerance of a primary hydroobject; a component consisting solely of secondary objects is unconnected. Comparisons include vertices and every position along a line segment, so they do not depend on endpoint-based hydroobject_verbinding records. Those records are retained as an argument for API compatibility and are inspected only to warn about unknown source identifiers.

Parameters:

Name	Type	Description	Default
hydroobject_secundair	GeoDataFrame	Original selected secondary hydroobjecten with unique, non-empty bron_id values.	required
hydroobject_primair	GeoDataFrame	Original selected primary hydroobjecten with unique, non-empty bron_id values.	required
hydroobject_verbinding	GeoDataFrame	Existing directed connection layer. It does not determine the spatial classification.	required
tolerance	float	Maximum distance in metres in the configured project CRS, by default 2. Must be at least zero.	2.0

Returns:

Type	Description
tuple[GeoDataFrame, GeoDataFrame]	Connected secondary hydroobjecten followed by unconnected secondary hydroobjecten. Both preserve the input schema, order, and CRS.

Raises:

Type	Description
ValueError	If a non-empty source layer has missing or duplicate bron_id values, or tolerance is negative.

split_hydroobjecten_at_points(hydroobjecten, puntobjecten, *, tolerance)

Split hydroobjecten at nearby points and derive inter-line connections.

A point is projected to each LineString at distance no greater than tolerance. Internal, unique projected positions split the source line. Endpoint positions are intentionally not split. Connections are derived after the final length segmentation, because only then every connection can refer to final segment_id values.

Parameters:

Name	Type	Description	Default
hydroobjecten	GeoDataFrame	LineString or MultiLineString source features. Missing source IDs are derived safely from globalid, code, or the row index.	required
puntobjecten	GeoDataFrame	Point source features. Relevant point attributes are copied to derived connection records.	required
tolerance	float	Maximum projected point-to-line distance in project-CRS units.	required

Returns:

Type	Description
WatersysteemResult	Split source lines and deterministic point-induced connections, both in settings.crs.

split_hydroobjecten_by_length(hydroobjecten, *, max_length)

Split lines into equal-length segments no longer than max_length.

The number of segments is the smallest integer that keeps each segment at or below max_length. The source line length is then divided equally over those segments. Source fields and bron_id are retained. segment_id is based on the source identifier and a deterministic, one-based sequence number.

waterbeheercode_from_nen3610id(value)

Extract the waterbeheerder code from a HyDAMO NEN3610 identifier.

write_watersysteem(*, hydroobject_primair, hydroobject_secundair, watersysteem, data_store=None, output_path=None, overwrite=False, secondary_connection_tolerance=2.0)

Atomically write the prepared watersysteem layers to a GeoPackage.

Existing output is reused only when it passes the required GeoPackage, layer, and CRS validation. A failed write or validation removes its temporary file and leaves an existing target untouched. Layers with a bundled QML style register that style in the GeoPackage automatically.

Parameters:

Name	Type	Description	Default
hydroobject_primair	GeoDataFrame	Selected primary source hydroobjecten. Written without topology changes.	required
hydroobject_secundair	GeoDataFrame	Selected secondary source hydroobjecten. They are divided into connected and unconnected output layers using their complete line geometry.	required
watersysteem	WatersysteemResult	Geometrically prepared primary segments and point-induced connections.	required
data_store	DataStore	Supplies the default output directory.	None
output_path	Path	Override for the target GeoPackage. Defaults to datastore.afwateringseenheden_path / 'watersysteem.gpkg'.	None
overwrite	bool	Whether to replace an existing valid GeoPackage. With False, a valid target is reused; an invalid target is replaced only after a new temporary GeoPackage has been validated.	False
secondary_connection_tolerance	float	Maximum distance in metres between complete primary and secondary hydroobject geometries when classifying connected secondary objects, by default 2.	2.0

Returns:

Type	Description
Path	Validated GeoPackage with exactly the required output layers.

Redactie: AI