Utils#

Module for loading and processing geospatial data from Overture Maps.

city2graph.utils.create_tessellation(geometry, primary_barriers=None, shrink=0.4, segment=0.5, threshold=0.05, n_jobs=-1, **kwargs)[source]#

Create tessellations from the given geometries.

If primary_barriers are provided, enclosed tessellations are created. If not, morphological tessellations are created. For more details, see momepy.enclosed_tessellation and momepy.morphological_tessellation.

Parameters:

  • geometry (Union[geopandas.GeoDataFrame, geopandas.GeoSeries]) – Input geometries to create a tessellation for. Should contain the geometries to tessellate.

  • primary_barriers (Optional[Union[gpd.GeoDataFrame, gpd.GeoSeries]], default=None) – Optional GeoDataFrame or GeoSeries containing barriers to use for enclosed tessellation. If provided, the function will create enclosed tessellation using these barriers. If None, morphological tessellation will be created using the input geometries.

  • shrink (float, default=0.4) – Distance for negative buffer of tessellations. By default, 0.4. Used for both momepy.enclosed_tessellation and momepy.morphological_tessellation.

  • segment (float, default=0.5) – Maximum distance between points for tessellations. By default, 0.5. Used for both momepy.enclosed_tessellation and momepy.morphological_tessellation.

  • threshold (float, default=0.05) – Minimum threshold for a building to be considered within an enclosure. By default, 0.05. Used for both momepy.enclosed_tessellation.

  • n_jobs (int, default=-1) – Number of parallel jobs to run. By default, -1 (use all available cores). Used for both momepy.enclosed_tessellation.

  • **kwargs (Any) – Additional keyword arguments to pass to momepy.enclosed_tessellation. These can include parameters specific to the tessellation method used.

Returns:

GeoDataFrame containing the tessellation polygons.

Return type:

geopandas.GeoDataFrame

city2graph.utils.dual_graph(gdf, id_col=None, tolerance=1e-08)[source]#

Convert a GeoDataFrame to a NetworkX graph and then back to a GeoDataFrame.

Also detects connections where endpoints of one linestring are on another linestring.

Parameters:

  • gdf (geopandas.GeoDataFrame) – GeoDataFrame containing LineString geometries to convert

  • id_col (str, default None) – Column name that uniquely identifies each feature If None, will use DataFrame index

  • tolerance (float, default 1e-8) – Distance tolerance for detecting endpoint connections

Returns:

(GeoDataFrame of nodes, dict of connections)

Return type:

tuple

Raises:

  • TypeError – If input is not a GeoDataFrame or if tolerance is not a number

  • ValueError – If GeoDataFrame is empty or contains invalid geometries

city2graph.utils.filter_graph_by_distance(graph, center_point, distance, edge_attr='length', node_id_col=None)[source]#

Extract a filtered graph containing only elements within a given shortest-path distance.

Filters graph elements based on distance from specified center point(s).

Parameters:

  • graph (Union[gpd.GeoDataFrame, nx.Graph]) – Input graph data as either a GeoDataFrame of edges or a NetworkX graph.

  • center_point (Union[Point, gpd.GeoSeries, gpd.GeoDataFrame]) – Center point(s) for distance calculation. Can be a single Point, GeoSeries of points, or GeoDataFrame with point geometries.

  • distance (float) – Maximum shortest-path distance from any center node.

  • edge_attr (str, default="length") – Edge attribute to use as weight for distance calculation.

  • node_id_col (Optional[str], default=None) – Column name in nodes GeoDataFrame to use as node identifier. If None, will use auto-generated node IDs.

Returns:

Filtered graph containing only elements within distance of any center point. Returns the same type as the input (either GeoDataFrame or NetworkX graph).

Return type:

Union[gpd.GeoDataFrame, nx.Graph]

city2graph.utils.gdf_to_nx(nodes=None, edges=None, node_id_col=None, edge_id_col=None, keep_geom=True)[source]#

Convert GeoDataFrames of nodes and edges to a NetworkX graph.

Parameters:

  • nodes (GeoDataFrame, optional) – Point or Polygon geometries for graph nodes; node attributes preserved.

  • edges (GeoDataFrame) – LineString geometries for graph edges; edge attributes preserved.

  • node_id_col (str, optional) – Column name to use for node identifiers; if None, sequential IDs are assigned.

  • edge_id_col (str, optional) – Column name to use for edge identifiers; if None, sequential IDs are assigned.

  • keep_geom (bool, default=True) – If True, include original geometry columns on edges.

Returns:

Graph with ‘crs’, ‘node_geom_cols’, ‘edge_geom_cols’, node ‘pos’, and attributes.

Return type:

networkx.Graph

city2graph.utils.nx_to_gdf(G, nodes=False, edges=False)[source]#

Convert a NetworkX graph to a GeoDataFrame for nodes or edges.

Parameters:

  • G (networkx.Graph) – Graph with ‘crs’, ‘node_geom_cols’, and ‘edge_geom_cols’ in G.graph.

  • nodes (bool, default=False) – If True, return node GeoDataFrame.

  • edges (bool, default=False) – If True, return edge GeoDataFrame.

Returns:

GeoDataFrame with correct CRS and all geometry columns as GeoSeries.

Return type:

geopandas.GeoDataFrame

Raises:

ValueError – If required ‘pos’ or geometry attributes are missing, or if both/neither flags are set.