network_snapping
network_snapping
Route link geometries of a Ribasim-scheme along the network of hydro-objects.
Nodes are never moved: connector nodes stay at the location of the structure they represent, and Basin nodes stay where they are. Only the geometries of the flow links between a Basin and a connector node are changed. Such a link is drawn as a straight line from the connector node to the nearest hydro-object within the basin area, followed by the shortest route along the hydro-objects to the point nearest to the Basin node, and a straight line to the Basin node. Links that share a route can afterwards be merged with ribasim_nl.junctions.junctionify.
This relies on the network of hydro-objects written by the network-based profile-generation: src/ribasim_nl/ribasim_nl/profiles/*.py.
Functions
| Name | Description |
|---|---|
| lines_in | Indices and LineString parts of the geometries clipped to an area. |
| read_hydro_objects | Read the network of hydro-objects written by the profile-generation. |
| read_main_waterways | The Top10NL water lines within a mask, and the lines of the main_route as its main route. |
| read_waterways | Read the water lines of the Top10NL, or of a dataset in its format, within a mask, to complement the hydro-objects. |
| route_basin_links | Route the links between a Basin node and its connector nodes along the hydro-objects in the basin. |
| route_over_water | Route the links between a Basin node and its connector nodes over the water surface in the basin area. |
| snap_model | Snap a model to the hydro-objects of the profile-generation, see snap_to_network. |
| snap_to_network | Route flow links between a Basin and a connector node along the hydro-objects, and move Basin nodes onto them. |
| snap_to_waterways | Route links along the Top10NL water lines and over the Top10NL water surfaces, without moving nodes. |
| straight_flow_link_ids | The flow links with a straight geometry. |
| straight_link_geometries | Make link geometries start at their from-node and end at their to-node. |
lines_in
network_snapping.lines_in(geometries, tree, area)Indices and LineString parts of the geometries clipped to an area.
read_hydro_objects
network_snapping.read_hydro_objects(profiles_path)Read the network of hydro-objects written by the profile-generation.
read_main_waterways
network_snapping.read_main_waterways(top10nl_path, mask, main_route=None)The Top10NL water lines within a mask, and the lines of the main_route as its main route.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| top10nl_path | pathlib.Path | Top10NL GeoPackage | required |
| mask | shapely.Geometry | area to read | required |
| main_route | gpd.GeoDataFrame | None | lines of the main route, such as a network of main waterways, defaults to None | None |
Returns
| Name | Type | Description |
|---|---|---|
| gpd.GeoDataFrame | the waterways, with a boolean “main-route” column |
read_waterways
network_snapping.read_waterways(path, mask)Read the water lines of the Top10NL, or of a dataset in its format, within a mask, to complement the hydro-objects.
See scripts/download_gsk3e.py for such a dataset.
route_basin_links
network_snapping.route_basin_links(
basin_point,
connectors,
lines,
main_route,
*,
culverts=None,
water=None,
area=None,
basin_area=None,
max_gap=2.0,
max_water_gap=500.0,
culvert_snap=10.0,
max_attach_distance=100.0,
max_land=MAX_LAND,
max_straight_line_ratio=MAX_STRAIGHT_LINE_RATIO,
min_routed_fraction=0.5,
)Route the links between a Basin node and its connector nodes along the hydro-objects in the basin.
The hydro-objects are connected by the culverts, and dangling ends are connected to other parts of the network if the gap is small or crossed over water, see _BasinNetwork.bridge_gaps. Then only the longest connected part of the network is used. The Basin node is attached to its nearest main route hydro-object in this part (if any), and each connector node to its nearest hydro-object within max_attach_distance. Connector nodes farther away are attached over the water within area instead, crossing at most max_land of land, see _WaterRaster. All routes follow the shortest paths from the Basin node, such that routes share their common parts exactly.
If basin_area is given and contains the attachment point of the Basin node, and at least min_routed_fraction of the links can be routed from there, the Basin node is moved there. A route is not used if it is not less than max_straight_line_ratio times the straight line, as in ribasim_nl.link_geometries.fix_link_geometries.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| basin_point | shapely.Point | location of the Basin node | required |
| connectors | dict[int, shapely.Point] | locations of the connector nodes, by key | required |
| lines | list[shapely.LineString] | hydro-objects within the basin area | required |
| main_route | list[bool] | per hydro-object, whether it is part of the main route | required |
| culverts | list[shapely.LineString] | None | culverts within the basin area, defaults to None | None |
| water | shapely.Geometry | None | water surface within the basin area, defaults to None | None |
| area | shapely.Geometry | None | area within which routes over water are found, defaults to None (no routes over water) | None |
| basin_area | shapely.Polygon | shapely.MultiPolygon | None | area within which the Basin node may be moved onto the network, defaults to None (not moved) | None |
| max_gap | float | maximum gap between hydro-objects to bridge | 2.0 |
| max_water_gap | float | maximum gap between hydro-objects to bridge over water | 500.0 |
| culvert_snap | float | maximum distance between a culvert end and the hydro-objects | 10.0 |
| max_attach_distance | float | maximum distance between a connector node and the network | 100.0 |
| max_land | float | maximum length of land crossed by a route over water | MAX_LAND |
| max_straight_line_ratio | float | maximum ratio between route length and straight line length | MAX_STRAIGHT_LINE_RATIO |
| min_routed_fraction | float | minimum fraction of the links that can be routed to move the Basin node | 0.5 |
Returns
| Name | Type | Description |
|---|---|---|
| tuple[shapely.Point, dict[int, list[Coord]]] | the (possibly moved) location of the Basin node, and per routed connector key the coordinates from the Basin node to the connector node |
route_over_water
network_snapping.route_over_water(
basin_point,
connectors,
water,
area,
*,
land_cost=20.0,
max_land=MAX_LAND,
max_cells=1000000,
max_straight_line_ratio=MAX_STRAIGHT_LINE_RATIO,
)Route the links between a Basin node and its connector nodes over the water surface in the basin area.
This is for basins without hydro-objects, such as lakes and harbours, see _WaterRaster. Routes that cross more than max_land of land, or are not less than max_straight_line_ratio times the straight line, are not used.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| basin_point | shapely.Point | location of the Basin node | required |
| connectors | dict[int, shapely.Point] | locations of the connector nodes, by key | required |
| water | shapely.Geometry | water surface within the basin area | required |
| area | shapely.Geometry | the basin area, outside which routes cannot go | required |
| land_cost | float | cost of crossing land relative to water | 20.0 |
| max_land | float | maximum length of land crossed by a route | MAX_LAND |
| max_cells | int | maximum number of raster cells, which sets the cell size | 1000000 |
| max_straight_line_ratio | float | maximum ratio between route length and straight line length | MAX_STRAIGHT_LINE_RATIO |
Returns
| Name | Type | Description |
|---|---|---|
| dict[int, list[Coord]] | per routed connector key, the coordinates from the Basin node to the connector node |
snap_model
network_snapping.snap_model(
model,
profiles_path,
*,
crossings_path=None,
water_path=None,
waterway_paths=(),
tolerance=10.0,
routing_areas=None,
)Snap a model to the hydro-objects of the profile-generation, see snap_to_network.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| model | Model | Ribasim model | required |
| profiles_path | pathlib.Path | directory with the network.gpkg of the profile-generation | required |
| crossings_path | pathlib.Path | None | GeoPackage with a duikersifonhevel layer of culverts, defaults to None | None |
| water_path | pathlib.Path | None | GeoParquet with water surfaces, see ribasim_nl.bgt_water, defaults to None |
None |
| waterway_paths | typing.Sequence[pathlib.Path] | GeoPackages of which the water lines complement the hydro-objects, the Top10NL and possibly others in its format, see read_waterways, defaults to none |
() |
| tolerance | float | buffer around the basin area within which hydro-objects are used, defaults to 10.0 | 10.0 |
| routing_areas | dict[int, shapely.Geometry] | None | per Basin, an area beyond its basin area in which it is routed, see snap_to_network |
None |
snap_to_network
network_snapping.snap_to_network(
model,
hydro_objects,
*,
culverts=None,
water=None,
tolerance=10.0,
move_basins=True,
route_water=True,
link_ids=None,
routing_areas=None,
)Route flow links between a Basin and a connector node along the hydro-objects, and move Basin nodes onto them.
Connector nodes are never moved, such that they stay at the location of the structure they represent. Basin nodes are moved onto the main route nearest to them if move_basins is True, see route_basin_links, and the nodes of their bergend part along with them. Links that cannot be routed, links to bergend basins and links to boundary nodes keep their geometry, unless it does not connect their nodes, see straight_link_geometries.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| model | Model | Ribasim model | required |
| hydro_objects | gpd.GeoDataFrame | hydro-objects, with a boolean “main-route” column | required |
| culverts | gpd.GeoDataFrame | None | culverts (lines) that connect hydro-objects, defaults to None | None |
| water | gpd.GeoDataFrame | None | water surfaces (polygons), across which hydro-objects may be connected, defaults to None | None |
| tolerance | float | buffer around the basin area within which hydro-objects are used, defaults to 10.0 | 10.0 |
| move_basins | bool | move non-bergend Basin nodes onto the network, defaults to True | True |
| route_water | bool | route links that cannot be routed along the hydro-objects over the water surface, see route_basin_links, defaults to True |
True |
| link_ids | list[int] | None | only route these links, defaults to None (all) | None |
| routing_areas | dict[int, shapely.Geometry] | None | per Basin, an area beyond its basin area in which the hydro-objects are used as well, for connector nodes that are connected to it over a long distance, for instance through Germany | None |
Returns
| Name | Type | Description |
|---|---|---|
| Model | updated Ribasim model |
snap_to_waterways
network_snapping.snap_to_waterways(
model,
top10nl_path,
link_ids,
*,
main_route=None,
tolerance=10.0,
)Route links along the Top10NL water lines and over the Top10NL water surfaces, without moving nodes.
This is a fallback for links that cannot be routed along the hydro-objects of a water authority, see snap_to_network.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| model | Model | Ribasim model | required |
| top10nl_path | pathlib.Path | Top10NL GeoPackage | required |
| link_ids | list[int] | links to route | required |
| main_route | gpd.GeoDataFrame | None | lines of the main route, such as a network of main waterways, defaults to None | None |
| tolerance | float | buffer around the basin area within which waterways are used, defaults to 10.0 | 10.0 |
Returns
| Name | Type | Description |
|---|---|---|
| Model | updated Ribasim model |
straight_flow_link_ids
network_snapping.straight_flow_link_ids(model)The flow links with a straight geometry.
straight_link_geometries
network_snapping.straight_link_geometries(model, tolerance=1.0)Make link geometries start at their from-node and end at their to-node.
Link ends within tolerance of their node are moved onto it, other link geometries are replaced by straight lines.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| model | Model | Ribasim model | required |
| tolerance | float | maximum distance between a link end and its node to keep the link geometry | 1.0 |
Returns
| Name | Type | Description |
|---|---|---|
| Model | updated Ribasim model |