cartography Namespace Reference

Functions
tuple|nx.DiGraph	get_cartography (str|None place_name=None, tuple[float, float, float, float]|None bbox=None, str network_type="drive", bool|float consolidate_intersections=10, bool dead_ends=False, bool infer_speeds=False, str return_type="gdfs")
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)

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] cartography.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.
    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'.

get_cartography()

tuple | nx.DiGraph cartography.get_cartography	(	str | None	place_name = None,
		tuple[float, float, float, float] | None	bbox = None,
		str	network_type = "drive",
		bool | float	consolidate_intersections = 10,
		bool	dead_ends = False,
		bool	infer_speeds = False,
		str	return_type = "gdfs" )

Retrieves and processes cartography data for a specified place using OpenStreetMap data.

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.
    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.
    return_type (str, optional): Type of return value. Options are "gdfs" (GeoDataFrames) or
        "graph" (NetworkX DiGraph). Defaults to "gdfs".

Returns:
    tuple | nx.DiGraph: If return_type is "gdfs", returns a tuple containing two GeoDataFrames:
        - 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'.
        If return_type is "graph", returns the NetworkX DiGraph with standardized attributes.

graph_from_gdfs()

nx.DiGraph cartography.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] cartography.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.