Functions
nx.MultiDiGraph	fetch_cartography (str\|None place_name=None, tuple[float, float, float, float]\|None bbox=None, Polygon\|None polygon=None, str network_type="drive", str\|list[str]\|None custom_filter=None)
tuple[nx.DiGraph, gpd.GeoDataFrame, gpd.GeoDataFrame]	process_cartography (nx.MultiDiGraph G, bool\|float consolidate_intersections=10, bool dead_ends=False, bool infer_speeds=False, bool scc=False)
tuple[nx.DiGraph, gpd.GeoDataFrame, gpd.GeoDataFrame]	get_cartography (str\|None place_name=None, tuple[float, float, float, float]\|None bbox=None, Polygon\|None polygon=None, str network_type="drive", bool\|float consolidate_intersections=10, bool dead_ends=False, bool infer_speeds=False, str\|list[str]\|None custom_filter=None, bool scc=False)
nx.DiGraph	graph_from_gdfs (gpd.GeoDataFrame gdf_edges, gpd.GeoDataFrame gdf_nodes)
tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]	graph_to_gdfs (nx.DiGraph G)
tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]	create_manhattan_cartography (int n_x=10, int n_y=10, float spacing=2000.0, float maxspeed=50.0, float center_lat=0.0, float center_lon=0.0)
folium.Map	to_folium_map (nx.DiGraph G, str which="edges")

Detailed Description

@file cartography.py
@brief Cartography utilities for retrieving and processing OpenStreetMap data.

This module provides functions to download and process street network data
from OpenStreetMap using OSMnx, with support for graph simplification and
standardization of attributes.

Function Documentation

◆ create_manhattan_cartography()

tuple[gpd.GeoDataFrame, gpd.GeoDataFrame] create_manhattan_cartography	(	int	n_x = 10,
		int	n_y = 10,
		float	spacing = 2000.0,
		float	maxspeed = 50.0,
		float	center_lat = 0.0,
		float	center_lon = 0.0 )

Creates a synthetic street network with specified topology.

Args:
    n_x (int): Number of nodes in the x-direction (longitude). Defaults to 10.
    n_y (int): Number of nodes in the y-direction (latitude). Defaults to 10.
    spacing (float): Distance between nodes in meters. Defaults to 2000.0.
    maxspeed (float): Maximum speed for all edges in km/h. Defaults to 50.0.
    center_lat (float): Latitude of the network center. Defaults to 0.0.
    center_lon (float): Longitude of the network center. Defaults to 0.0.

Returns:
    tuple: A tuple containing two GeoDataFrames:
        - gdf_edges: GeoDataFrame with edge data, including columns like 'id', 'source',
          'target', 'nlanes', 'type', 'name', 'length', and 'geometry'.
        - gdf_nodes: GeoDataFrame with node data, including columns like 'id', 'type',
          and 'geometry'.

◆ fetch_cartography()

nx.MultiDiGraph fetch_cartography	(	str \| None	place_name = None,
		tuple[float, float, float, float] \| None	bbox = None,
		Polygon \| None	polygon = None,
		str	network_type = "drive",
		str \| list[str] \| None	custom_filter = None )

Downloads a raw cartography from OpenStreetMap.

Returns an unsimplified OSMnx MultiDiGraph with original OSM attributes
intact, ready to be processed by `process_street_network` or any custom
pipeline.

Args:
    place_name (str | None): Place name to geocode (e.g. "Bologna, Italy").
    bbox (tuple[float, float, float, float] | None): Bounding box (north, south, east, west). Used if place_name is None.
    polygon (Polygon | None): Polygon to use for filtering the graph. Used if place_name and bbox are None.
    network_type (str): OSMnx network type ("drive", "walk", "bike", …).
    custom_filter (str | list[str] | None): Raw OSM filter string or list of strings.

Returns:
    nx.MultiDiGraph: Raw, unsimplified graph in WGS-84 (lat/lon).

◆ get_cartography()

tuple[nx.DiGraph, gpd.GeoDataFrame, gpd.GeoDataFrame] get_cartography	(	str \| None	place_name = None,
		tuple[float, float, float, float] \| None	bbox = None,
		Polygon \| None	polygon = None,
		str	network_type = "drive",
		bool \| float	consolidate_intersections = 10,
		bool	dead_ends = False,
		bool	infer_speeds = False,
		str \| list[str] \| None	custom_filter = None,
		bool	scc = False )

Retrieves and processes cartography data for a specified place using OpenStreetMap data.
This function calls `fetch_cartography` to download the raw graph and then `process_cartography` to clean and standardize it.

This function downloads a street network graph for the given place or bounding box, optionally consolidates
intersections to simplify the graph, removes edges with zero length, self-loops and isolated nodes,
and standardizes the attribute names in the graph. Can return either GeoDataFrames or the graph itself.

Args:
    place_name (str): The name of the place (e.g., city, neighborhood) to retrieve cartography for.
    bbox (tuple, optional): A tuple specifying the bounding box (north, south, east, west)
        to retrieve cartography for.
    polygon (Polygon, optional): A Polygon to use for retrieving cartography.
    network_type (str, optional): The type of network to retrieve. Common values include "drive",
        "walk", "bike". Defaults to "drive".
    consolidate_intersections (bool | float, optional): If True, consolidates intersections using
        a default tolerance. If a float, uses that value as the tolerance for consolidation.
        Set to False to skip consolidation. Defaults to 10.
    dead_ends (bool, optional): Whether to include dead ends when consolidating intersections.
        Only relevant if consolidate_intersections is enabled. Defaults to False.
    infer_speeds (bool, optional): Whether to infer edge speeds based on road types. Defaults to False.
        If True, calls ox.routing.add_edge_speeds using np.nanmedian as aggregation function.
        Finally, the "maxspeed" attribute is replaced with the inferred "speed_kph", and the "travel_time" attribute is computed.
    custom_filter (str | list[str], optional): A custom OSM filter string or list of strings to apply when retrieving the graph. Defaults to None.
    scc (bool, optional): Whether to keep only the largest strongly connected component of the graph. Defaults to False.

Returns:
    tuple[nx.DiGraph, gpd.GeoDataFrame, gpd.GeoDataFrame]: Returns a tuple containing:
        - NetworkX DiGraph with standardized attributes.
        - gdf_edges: GeoDataFrame with processed edge data, including columns like 'source',
          'target', 'nlanes', 'type', 'name', 'id', and 'geometry'.
        - gdf_nodes: GeoDataFrame with processed node data, including columns like 'id', 'type',
          and 'geometry'.

◆ graph_from_gdfs()

nx.DiGraph graph_from_gdfs	(	gpd.GeoDataFrame	gdf_edges,
		gpd.GeoDataFrame	gdf_nodes )

Constructs a NetworkX DiGraph from given GeoDataFrames of edges and nodes.
The supported GeoDataFrame are the ones returned by get_cartography with return_type="gdfs".

Args:
    gdf_edges (GeoDataFrame): GeoDataFrame containing edge data.
    gdf_nodes (GeoDataFrame): GeoDataFrame containing node properties data.

Returns:
    nx.DiGraph: The constructed DiGraph with standardized attributes.

◆ graph_to_gdfs()

tuple[gpd.GeoDataFrame, gpd.GeoDataFrame] graph_to_gdfs ( nx.DiGraph G )

Converts a NetworkX DiGraph to GeoDataFrames of edges and nodes.
The returned GeoDataFrames are compatible with those returned by get_cartography with return_type="gdfs".

Args:
    G (nx.DiGraph): The input DiGraph.

Returns:
    tuple: A tuple containing two GeoDataFrames:
        - gdf_edges: GeoDataFrame with edge data.
        - gdf_nodes: GeoDataFrame with node properties data.

◆ process_cartography()

tuple[nx.DiGraph, gpd.GeoDataFrame, gpd.GeoDataFrame] process_cartography	(	nx.MultiDiGraph	G,
		bool \| float	consolidate_intersections = 10,
		bool	dead_ends = False,
		bool	infer_speeds = False,
		bool	scc = False )

Processes and standardizes a raw OSMnx cartography.

Accepts any MultiDiGraph (e.g. from `fetch_cartography` or loaded from
disk) and applies geometry simplification, optional intersection
consolidation, attribute normalization, and optional speed inference.

Args:
    G (nx.MultiDiGraph): Raw OSMnx MultiDiGraph in WGS-84 (lat/lon).
    consolidate_intersections (bool | float, optional): Tolerance in metres for intersection
        consolidation. Pass False to skip. True uses the default (10 m). Defaults to 10.
    dead_ends (bool, optional): Whether to preserve dead-end nodes during consolidation. Defaults to False.
    infer_speeds (bool, optional): If True, infers edge speeds via np.nanmedian and
        computes travel times. Defaults to False.
    scc (bool, optional): If True, keeps only the largest strongly connected component of the graph. Defaults to False.

Returns:
    tuple:
        - nx.DiGraph with standardized attributes.
        - gdf_edges: edges with columns source, target, nlanes, type,
          name, id, geometry, ...
        - gdf_nodes: nodes with columns id, type, geometry, ...

◆ to_folium_map()

folium.Map to_folium_map	(	nx.DiGraph	G,
		str	which = "edges" )

Converts a NetworkX DiGraph to a Folium map for visualization.
Args:
    G (nx.DiGraph): The input DiGraph.
    which (str): Specify whether to visualize 'edges', 'nodes', or 'both'. Defaults to 'edges'.
Returns:
    folium.Map: The Folium map with the graph visualized.

Functions

Detailed Description

Function Documentation

◆ create_manhattan_cartography()

◆ fetch_cartography()

◆ get_cartography()

◆ graph_from_gdfs()

◆ graph_to_gdfs()

◆ process_cartography()

◆ to_folium_map()