iduedu.project_objects2urban_graph¶

iduedu.project_objects2urban_graph(graph_gdf, objects_gdf, speed_m_per_min, *, max_dist=None, add_link_edge=True)[source]¶

Prepare graph changes that connect objects to their nearest edges.

The function does not mutate the source graph. It computes nodes and edges to add, source edges to remove, and an object2node mapping. In backend services this is the preferred low-level workflow: changes can be persisted to graph tables and object2node_map can be saved on the object table as graph_node_id. For in-memory workflows, apply the result with apply_urban_graph_changes().

Objects are projected by their representative_point(), so the function works for buildings, services and other polygon or point layers with a stable unique index.

Parameters:

graph_gdf (UrbanGraph) – Source urban graph.
objects_gdf (GeoDataFrame) – Objects to connect to the graph. The index should be a stable object identifier, such as object_id or building_id.
speed_m_per_min (float) – Movement speed on created connector edges, in meters per minute. For 5 km/h use 5 * 1000 / 60.
max_dist (float | None) – Optional maximum distance from an object to the nearest edge. If None, nearest edges are searched without a distance limit.
add_link_edge (bool) – If True, create a dedicated object node and connector edge. If False, map the object to the projection node on the graph.

Return type:

tuple[UrbanGraphChanges, Series]

Returns:

Pair (changes, object2node_map). changes.nodes_gdf contains new nodes, changes.edges_gdf contains new edges, and changes.edges_to_delete contains replaced edge keys. object2node_map is a Series indexed by the original object index with graph node ids as values.

Raises:

TypeError – If objects_gdf is not a GeoDataFrame.
ValueError – If objects are empty or speed/distance parameters are invalid.