networkforge 1.4.1__py3-none-any.whl

networkforge/points.py

@@ -0,0 +1,290 @@
+"""
+Points in the custom layer: barriers, traffic signals, crossings ...
+
+A point feature with node tags (barrier=bollard, highway=traffic_signals,
+crossing=zebra, ...) puts those tags on the network at that place, as an
+OSM node of the street:
+
+    - within snap_tolerance of a node (a junction, or any node of an
+      existing street): that node gets the tags, e.g. signals at an
+      existing junction;
+    - otherwise on the nearest street within snap_tolerance - new line,
+      existing street or changed street alike: the street is cut there
+      and a new node carries the tags, e.g. a bollard mid-block.
+
+`remove_tags` deletes tags from the node the point is on (an existing
+bollard taken out: remove_tags=barrier). Points are placed on the
+FINISHED network (place_points), like turn restrictions, and never touch
+the "before" network.
+"""
+
+import logging
+
+import geopandas as gpd
+import numpy as np
+import pandas as pd
+import shapely
+import shapely.ops
+
+from .errors import InputError, InvalidTagsError
+from .tags import (
+    CUSTOM_COLUMN,
+    MODIFIED_COLUMN,
+    NODE_TAGS,
+    REMOVE_TAGS_COLUMN,
+    ROUTING_NODE_KEYS,
+)
+from .validation import ACCESS_KEYS, ACCESS_VALUES, _tag_value, warn_about_unknown_values
+
+log = logging.getLogger(__name__)
+
+POINT_TYPES = {"Point", "MultiPoint"}
+
+# Tags a point may put on a node: those routers read on nodes.
+POINT_TAG_KEYS = tuple(dict.fromkeys((*ROUTING_NODE_KEYS, "traffic_calming", "kerb")))
+
+# `highway` values for nodes (a way value such as "residential" on a
+# point is a mistake), and the barriers routers know. Unknown barrier
+# and crossing values only warn, as for way tags.
+NODE_HIGHWAYS = {
+    "traffic_signals", "crossing", "stop", "give_way", "mini_roundabout", "turning_circle",
+    "turning_loop", "motorway_junction", "speed_camera", "elevator", "milestone",
+    "passing_place", "bus_stop", "street_lamp", "toll_gantry", "ford", "traffic_mirror",
+}
+NODE_KNOWN_VALUES = {
+    "barrier": {
+        "bollard", "gate", "lift_gate", "swing_gate", "sliding_gate", "wicket_gate", "block",
+        "cycle_barrier", "kissing_gate", "stile", "turnstile", "full-height_turnstile",
+        "chain", "rope", "bus_trap", "sump_buster", "toll_booth", "border_control", "entrance",
+        "height_restrictor", "jersey_barrier", "kerb", "spikes", "motorcycle_barrier", "debris",
+        "log", "hampshire_gate", "sally_port", "planter", "yes",
+    },
+    "crossing": {
+        "traffic_signals", "uncontrolled", "marked", "unmarked", "zebra", "no", "informal",
+        "island", "toucan", "pelican", "pegasus", "puffin",
+    },
+    "railway": {"level_crossing", "crossing"},
+    "traffic_calming": {
+        "bump", "hump", "table", "cushion", "chicane", "choker", "island", "rumble_strip",
+        "dip", "mini_bumps", "yes",
+    },
+}
+
+# Two streets closer than this to a point (m) are both "under" it: a
+# bridge over a street, say. `layer` on the point picks one.
+SAME_PLACE = 0.01
+
+
+def split_points(custom_gdf: gpd.GeoDataFrame) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]:
+    """(line features, point features, one row per point) of cleaned custom data."""
+    is_point = custom_gdf.geometry.geom_type.isin(POINT_TYPES).to_numpy()
+    if not is_point.any():
+        return custom_gdf, custom_gdf.iloc[:0]
+    points = custom_gdf[is_point].explode(index_parts=False)
+    return custom_gdf[~is_point], points
+
+
+def point_tags(row: pd.Series) -> dict[str, str]:
+    """The node tags a point feature carries."""
+    tags = {}
+    for key in POINT_TAG_KEYS:
+        if key in row.index:
+            text = _tag_value(row[key])
+            if text is not None:
+                tags[key] = text
+    return tags
+
+
+def tags_to_remove(row: pd.Series) -> list[str]:
+    """The keys a point's `remove_tags` lists (separated by ; or ,)."""
+    text = _tag_value(row.get(REMOVE_TAGS_COLUMN)) or ""
+    return list(dict.fromkeys(key.strip() for key in text.replace(",", ";").split(";")
+                              if key.strip()))
+
+
+def check_point_tags(points_gdf: gpd.GeoDataFrame, strict: bool = True) -> None:
+    """Each point must set or delete node tags, with values OSM knows."""
+    issues, unknown = [], {}
+    for feature, row in points_gdf.drop(columns=points_gdf.geometry.name).iterrows():
+        tags, removing = point_tags(row), tags_to_remove(row)
+        if not tags and not removing:
+            issues.append((feature, "a point needs node tags, e.g. barrier=bollard or "
+                                    "highway=traffic_signals"))
+        highway = tags.get("highway")
+        if highway is not None and highway not in NODE_HIGHWAYS:
+            issues.append((feature, f"highway={highway!r} is not a value for a point "
+                                    "(e.g. traffic_signals, crossing, stop, give_way)"))
+        for key in ACCESS_KEYS:
+            value = tags.get(key)
+            if value is not None and value not in ACCESS_VALUES:
+                issues.append((feature, f"{key}={value!r} is not a valid OSM access value"))
+        if "barrier" not in tags and any(key in tags for key in ACCESS_KEYS):
+            log.warning("Point %s has access tags but no barrier: routers ignore access on a "
+                        "node without one (add e.g. barrier=gate).", feature,
+                        extra={"features": [feature]})
+        for key in sorted(set(removing) & tags.keys()):
+            issues.append((feature, f"{key} is both given a value ({tags[key]!r}) and listed "
+                                    f"in {REMOVE_TAGS_COLUMN}"))
+        for key, values in NODE_KNOWN_VALUES.items():
+            if key in tags and tags[key] not in values:
+                unknown.setdefault((key, tags[key]), []).append(feature)
+
+    warn_about_unknown_values(unknown, NODE_KNOWN_VALUES)
+    if issues:
+        error = InvalidTagsError(issues)
+        if strict:
+            raise error
+        log.warning("strict=False, continuing anyway: %s", error,
+                    extra={"features": [i["feature"] for i in error.issues]})
+
+
+def place_points(
+    points_gdf: gpd.GeoDataFrame,
+    nodes_gdf: gpd.GeoDataFrame,
+    edges_gdf: gpd.GeoDataFrame,
+    tolerance: float,
+    first_new_id: int,
+    existing_tags: dict[int, dict[str, str]],
+    strict: bool = True,
+    osm_nodes=(),
+) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame, dict[int, dict[str, str | None]]]:
+    """
+    Put each point's tags on the network (see the module docstring).
+
+    Returns (nodes, edges, changes): copies of the tables, with streets
+    cut where a point needed a node of its own, and {node id: {key:
+    value, or None to delete}}. existing_tags: the tags nodes already
+    have (OSM's), to tell deletions that change nothing. Each node a
+    point tags is marked in the nodes table, as edges are: `modified` =
+    yes on an OpenStreetMap node (one of `osm_nodes`), `custom` = yes on
+    a node of the user's own (a new one, or on a custom line).
+    points_gdf in the network's CRS.
+    """
+    nodes, edges = nodes_gdf.copy(), edges_gdf.copy()
+    changes: dict[int, dict[str, str | None]] = {}
+    issues = []
+    next_id = first_new_id
+
+    for feature, row in points_gdf.iterrows():
+        point = row.geometry
+        tags, removing = point_tags(row), tags_to_remove(row)
+
+        # A node within reach: the nearest.
+        distances = nodes.geometry.distance(point)
+        node = None
+        if len(distances) and distances.min() <= tolerance:
+            node = int(distances.idxmin())
+        elif removing:
+            issues.append((feature, f"no node within {tolerance} m to delete tags from: put the "
+                                    "point on the node that has them"))
+            continue
+        else:
+            node, nodes, edges, problem = _cut_street(
+                point, row, nodes, edges, tolerance, next_id)
+            if problem:
+                issues.append((feature, problem))
+                continue
+            next_id += 1
+
+        change = changes.setdefault(node, {})
+        current = {**existing_tags.get(node, {}), **change}
+        for key, value in tags.items():
+            if key in change and change[key] != value:
+                issues.append((feature, f"another point sets {key}={change[key]!r} on the same "
+                                        f"node ({node})"))
+            change[key] = value
+        change |= {key: None for key in removing if key in current}
+        if not change:
+            log.warning("Point %s changes nothing: node %d has none of the tags in %s.",
+                        feature, node, REMOVE_TAGS_COLUMN, extra={"features": [feature]})
+            changes.pop(node)
+            continue
+        for key, value in change.items():
+            if key in NODE_TAGS:
+                if key not in nodes.columns:
+                    nodes[key] = None
+                nodes[key] = nodes[key].astype(object)
+                nodes.at[node, key] = value
+
+    if issues:
+        error = InputError(
+            "Some points can't be placed - "
+            + "; ".join(f"feature {feature}: {message}" for feature, message in issues) + ".",
+            guide="points-barriers-signals-crossings",
+            issues=[{"feature": feature, "message": message} for feature, message in issues],
+        )
+        if strict:
+            raise error
+        log.warning("strict=False, skipping them: %s", error,
+                    extra={"features": [feature for feature, _ in issues]})
+
+    osm_nodes = set(osm_nodes)
+    for node in changes:
+        column = MODIFIED_COLUMN if node in osm_nodes else CUSTOM_COLUMN
+        if column not in nodes.columns:
+            nodes[column] = None
+        nodes[column] = nodes[column].astype(object)
+        nodes.at[node, column] = "yes"
+
+    log.info("Points: %d node(s) tagged", len(changes))
+    return nodes, edges, changes
+
+
+def _cut_street(point, row, nodes, edges, tolerance, node_id):
+    """
+    Cut the street nearest `point` (within tolerance) there, with a new
+    node `node_id`. Returns (node id, nodes, edges, problem or None).
+    """
+    geometries = edges.geometry.to_numpy()
+    distances = shapely.distance(geometries, point)
+    near = distances <= tolerance
+    if not near.any():
+        return None, nodes, edges, f"not within {tolerance} m of a street"
+
+    # The street(s) right under the point; `layer` on the point picks one.
+    under = near & (distances <= distances[near].min() + SAME_PLACE)
+    layer = _tag_value(row.get("layer"))
+    if layer is not None and "layer" in edges:
+        on_layer = (edges["layer"].map(_tag_value).fillna("0") == layer).to_numpy()
+        under &= on_layer
+        if not under.any():
+            return None, nodes, edges, f"no street on layer {layer} within {tolerance} m"
+    pairs = {frozenset((u, v)) for u, v in zip(edges["u"][under], edges["v"][under], strict=True)}
+    if len(pairs) > 1:
+        return None, nodes, edges, (f"lies on {len(pairs)} streets (a bridge over a street?): "
+                                    "give the point the street's layer")
+
+    # The street, and OSMnx's copy of it drawn the other way.
+    nearest = np.flatnonzero(under)[0]
+    street = geometries[nearest]
+    on_street = shapely.line_interpolate_point(street, street.project(point))
+    pair = frozenset((edges["u"].iloc[nearest], edges["v"].iloc[nearest]))
+    same = np.array([frozenset((u, v)) == pair and shapely.equals(g, street)
+                     for u, v, g in zip(edges["u"], edges["v"], geometries, strict=True)])
+
+    pieces = []
+    for _, edge in edges[same].iterrows():
+        line = edge.geometry
+        at = line.project(on_street)
+        if at <= 0 or at >= line.length:  # pragma: no cover - the ends are nodes, found first
+            return None, nodes, edges, "lies on a node's place"
+        first, second = edge.copy(), edge.copy()
+        first.geometry = shapely.ops.substring(line, 0, at)
+        second.geometry = shapely.ops.substring(line, at, line.length)
+        first["v"] = second["u"] = node_id
+        for piece in (first, second):
+            if "length" in piece and piece["length"] == piece["length"]:
+                piece["length"] = edge["length"] * piece.geometry.length / line.length
+            if "split" in edges:
+                piece["split"] = "yes"
+        pieces += [first, second]
+
+    edges = pd.concat([edges[~same], gpd.GeoDataFrame(pieces, crs=edges.crs)],
+                      ignore_index=True)
+    edges = gpd.GeoDataFrame(edges, geometry="geometry", crs=nodes.crs)
+    new_node = gpd.GeoDataFrame(
+        geometry=[on_street], index=pd.Index([node_id], name=nodes.index.name), crs=nodes.crs)
+    if "street_count" in nodes:
+        new_node["street_count"] = 2
+    nodes = pd.concat([nodes, new_node])
+    return node_id, nodes, edges, None

networkforge/presets.py

@@ -0,0 +1,50 @@
+"""
+Ready-made tag sets for common kinds of custom infrastructure.
+
+A preset is the "blanket" option: pick one and every custom feature
+gets its tags (filling gaps, or replacing values with overwrite=True).
+Tags given alongside a preset (network_tags) take priority over it,
+which is how you add a speed limit:
+
+    build_network(bbox, custom, preset="primary_road",
+                  network_tags={"maxspeed": "40 mph"})
+
+Presets deliberately don't set maxspeed: limits differ by country, and
+without one the fixed DEFAULT_SPEEDS_KPH for the road type apply.
+
+See docs/network-rules.md for what each preset means and who can use it.
+"""
+
+from .errors import InputError
+
+PRESETS: dict[str, dict[str, str]] = {
+    # Roads (cars, bikes and pedestrians). A single drawn line carries
+    # traffic both ways; add oneway=yes for one direction only.
+    "motorway": {"highway": "motorway", "oneway": "no"},
+    "trunk_road": {"highway": "trunk", "oneway": "no"},
+    "primary_road": {"highway": "primary", "oneway": "no"},
+    "secondary_road": {"highway": "secondary", "oneway": "no"},
+    "tertiary_road": {"highway": "tertiary", "oneway": "no"},
+    "residential_street": {"highway": "residential", "oneway": "no"},
+    "service_road": {"highway": "service", "oneway": "no"},
+    # Active travel.
+    "cycleway": {"highway": "cycleway", "oneway": "no"},
+    "footpath": {"highway": "footway"},
+    "shared_path": {"highway": "path", "bicycle": "designated", "foot": "designated"},
+    # Cycling on a pedestrian street has to be allowed explicitly; leave
+    # the preset out and tag highway=pedestrian for walking only.
+    "pedestrian_street": {"highway": "pedestrian", "bicycle": "yes"},
+    # A road closed to motor traffic (e.g. a filtered street or bus gate).
+    "car_free_street": {"highway": "residential", "motor_vehicle": "no", "oneway": "no"},
+}
+
+
+def preset_tags(name: str) -> dict[str, str]:
+    """The tags for preset `name` (a copy, safe to modify)."""
+    try:
+        return dict(PRESETS[name])
+    except KeyError:
+        raise InputError(
+            f"Unknown preset {name!r}. Choose one of: {', '.join(PRESETS)}",
+            guide="presets",
+        ) from None

networkforge/projection.py

@@ -0,0 +1,81 @@
+import geopandas as gpd
+from pyproj import CRS
+
+from .errors import InputError
+
+
+def get_analysis_crs(
+    bbox: gpd.GeoDataFrame,
+) -> CRS:
+    """Determine the CRS to use for spatial analysis."""
+
+    if bbox.crs is None:
+        raise InputError(
+            "Bounding box must have a CRS assigned."
+        )
+
+    bbox_crs = CRS.from_user_input(bbox.crs)
+
+    if bbox_crs.is_projected and _is_local(bbox_crs):
+        return bbox_crs
+
+    bbox_wgs84 = bbox.to_crs("EPSG:4326")
+
+    centroid = bbox_wgs84.geometry.union_all().centroid
+
+    longitude = centroid.x
+    latitude = centroid.y
+
+    zone = int((longitude + 180) // 6) + 1
+
+    epsg = (
+        32600 + zone
+        if latitude >= 0
+        else 32700 + zone
+    )
+
+    return CRS.from_epsg(epsg)
+
+def _is_local(crs: CRS) -> bool:
+    """
+    True for a projected CRS made for one region (a UTM zone, a national
+    grid), where a metre on the map is a metre on the ground. Not for
+    world-wide projections such as Web Mercator (EPSG:3857, the default
+    of many web maps), which stretches distances by 1/cos(latitude):
+    lengths and the snap distance would be wrong by 80% in Scotland.
+    Nor for one measured in feet: everything here is in metres.
+    """
+    if any(axis.unit_name != "metre" for axis in crs.axis_info):
+        return False  # feet (US State Plane): lengths and the snap distance are metres
+    area = crs.area_of_use
+    if area is None:
+        return True  # a custom CRS: trust it
+    return (area.east - area.west) < 30
+
+
+def convert_to_wgs84_and_add_xy(
+    gdf: gpd.GeoDataFrame,
+) -> gpd.GeoDataFrame:
+    """
+    Convert a GeoDataFrame to WGS84 (EPSG:4326) and add
+    x/y coordinate columns.
+
+    Args:
+        gdf: GeoDataFrame to convert.
+
+    Returns:
+        GeoDataFrame in EPSG:4326 with x and y columns.
+    """
+
+    # OSM uses WGS84 coordinates.
+    if gdf.crs is None:
+        gdf = gdf.set_crs("EPSG:4326")
+
+    elif gdf.crs.to_string() != "EPSG:4326":
+        gdf = gdf.to_crs("EPSG:4326")
+
+    # Add longitude (x) and latitude (y) columns.
+    gdf["x"] = gdf.geometry.x.round(7)
+    gdf["y"] = gdf.geometry.y.round(7)
+
+    return gdf

networkforge/tags.py

@@ -0,0 +1,132 @@
+"""
+Which OpenStreetMap tags NetworkForge understands.
+
+Existing OSM ways, nodes and relations are written to .osm / .osm.pbf
+exactly as OpenStreetMap has them (every tag), so routers such as
+Valhalla see the real data. The lists here decide:
+
+- which attributes of a *custom* feature are written as tags (anything
+  else is not an OSM tag NetworkForge knows, and is left out);
+- which tags become columns of the edge / node tables (and so of the
+  GeoPackage). OSMnx discards every tag not in its `useful_tags_way` /
+  `useful_tags_node` settings; modes.keep_mode_tags() applies these
+  lists (plus every access tag the mode rules use) before any load;
+- which nodes and relations of a local extract are worth reading.
+"""
+
+# Core way tags, written first on export.
+BASE_WAY_TAGS = (
+    "highway", "name", "ref", "lanes", "maxspeed", "oneway", "access",
+    "service", "bridge", "tunnel", "layer", "junction", "surface", "width",
+)
+
+# Further way tags routers use: per-mode one-way and access, vehicle
+# restrictions, cycle infrastructure, and surface / difficulty.
+ROUTING_WAY_TAGS = (
+    # One-way exceptions (contraflow cycling, bus lanes)
+    "oneway:bicycle", "oneway:bus", "oneway:psv",
+    # Access for other vehicle types
+    "vehicle", "hgv", "goods", "bus", "psv", "motorcycle", "horse", "wheelchair",
+    "taxi", "hov", "moped", "emergency", "motorroad",
+    # Access that depends on the time of day, e.g. "no @ (Mo-Fr 07:00-09:00)"
+    "access:conditional", "motor_vehicle:conditional", "vehicle:conditional",
+    "hgv:conditional", "bicycle:conditional", "foot:conditional",
+    # Vehicle size / weight limits
+    "maxweight", "maxheight", "maxwidth", "maxlength", "maxaxleload", "maxaxles", "hazmat",
+    # Direction- and vehicle-specific speeds and lanes
+    "maxspeed:forward", "maxspeed:backward", "maxspeed:hgv",
+    "lanes:forward", "lanes:backward",
+    "turn:lanes", "turn:lanes:forward", "turn:lanes:backward",
+    # Names and signs used in turn-by-turn directions
+    "alt_name", "official_name", "int_ref", "destination", "destination:ref", "junction:ref",
+    # Walking, and ramps for wheelchairs, prams and bikes (on steps)
+    "sidewalk", "footway", "crossing",
+    "ramp", "ramp:wheelchair", "ramp:stroller", "ramp:bicycle",
+    # Cycle infrastructure
+    "cycleway", "cycleway:left", "cycleway:right", "cycleway:both",
+    "segregated", "bicycle_road", "cyclestreet", "shoulder",
+    # Surface and difficulty
+    "smoothness", "tracktype", "sac_scale", "incline", "lit", "ford", "toll",
+    # Ferries and shuttle trains (route=ferry without a highway tag)
+    "route", "duration",
+)
+
+# Node tags routers use: barriers (bollards, gates), signals,
+# crossings, level crossings, access on the barrier itself (lorries and
+# buses too), tolls, height / width / weight limits and entrances.
+NODE_TAGS = (
+    "highway", "barrier", "crossing", "railway", "junction", "ref",
+    "access", "vehicle", "motor_vehicle", "motorcar", "bicycle", "foot",
+    "bus", "psv", "hgv", "wheelchair",
+    "toll", "maxheight", "maxwidth", "maxweight", "entrance",
+)
+
+# A node of a local extract is read (with all its tags) if it has one
+# of these keys: NODE_TAGS plus further tags routers act on. Untagged
+# nodes, and nodes that are only e.g. a shop or a tree, carry nothing a
+# router uses.
+ROUTING_NODE_KEYS = (
+    *NODE_TAGS,
+    "bus", "psv", "hgv", "taxi", "motorcycle", "moped", "emergency", "horse", "wheelchair",
+    "bollard", "entrance", "toll", "traffic_signals", "traffic_signals:direction",
+    "direction", "maxheight", "maxwidth", "maxweight", "name", "exit_to", "level",
+)
+
+# Relations kept with the network: turn restrictions and lane
+# connectivity (by `type`), and the routes routers read names, refs and
+# cycle / walking networks from (type=route, by `route`).
+RELATION_TYPES = ("restriction", "connectivity")
+ROUTE_RELATIONS = ("road", "bicycle", "mtb", "foot", "hiking")
+
+# Ways without a `highway` tag that routers travel on: ferries and car
+# shuttle trains (`route=`). Existing ones are not part of NetworkForge's
+# own network (edge table, GeoPackage), but are written to the OSM file
+# as they are, so a router can use them; new ones drawn in the custom
+# layer join the network at their ends. Valhalla routes on nothing else
+# without a highway tag (not piers, platforms or squares mapped as areas).
+FERRY_ROUTES = ("ferry", "shuttle_train")
+
+# The column marking custom features, and the tag it's exported as.
+CUSTOM_COLUMN = "custom"
+CUSTOM_TAG = "nf:custom"
+
+# A custom feature with an OSM way id in one of these attributes changes
+# that existing way instead of adding a line (see edits.py). QuickOSM
+# layers have `osm_id`; NetworkForge's GeoPackage has `osmid`.
+EDIT_ID_COLUMNS = ("osm_id", "osmid")
+EDIT_ID_COLUMN = "osm_id"
+
+# On a feature with an OSM way id: `remove=yes` takes the stretch of the
+# way it lies along out of the network altogether.
+REMOVE_COLUMN = "remove"
+# On a feature with an OSM way id: `remove_tags=maxspeed;access` deletes
+# those tags from the stretch (an empty attribute only means "no change").
+REMOVE_TAGS_COLUMN = "remove_tags"
+REMOVED_ATTR = "networkforge_removed_edges"
+
+# Marks edges (and, as a tag, ways) whose tags an edit changed, and
+# which edit; the tag changes travel in edges.attrs[EDITS_ATTR].
+MODIFIED_COLUMN = "modified"
+MODIFIED_TAG = "nf:modified"
+EDIT_COLUMN = "nf_edit"
+EDITS_ATTR = "networkforge_edits"
+
+# Node tags set (or, as None, deleted) by points in the custom layer:
+# {node id: {key: value or None}}, carried to export like the edits.
+NODE_CHANGES_ATTR = "networkforge_node_changes"
+
+# Turn restrictions resolved on the built network (turns.Turn), carried
+# to export like the edits.
+TURNS_ATTR = "networkforge_turns"
+
+# Numbers the custom lines, so the pieces a line is cut into at
+# junctions can be written as one way again.
+PART_COLUMN = "nf_part"
+
+# Columns export.analysis_edges() adds to the GeoPackage edges for QGIS
+# network analysis.
+GPKG_ANALYSIS_COLUMNS = (
+    "car", "bike", "walk", "speed_kph", "length_m",
+    "car_minutes", "bike_minutes", "walk_minutes",
+    "car_direction", "bike_direction",
+)