(
nx_multigraph
:
networkx.classes.multigraph.MultiGraph
from_crs_code
:
int | str
to_crs_code
:
int | str
)->[
MultiGraph
]
Cityseer API Docs
io
Functions for fetching and converting graphs and network structures.
nx_epsg_conversion
nx_epsg_conversion
Convert a graph from the from_crs_code EPSG CRS to the to_crs_code EPSG CRS. The to_crs_code must be for a projected CRS. If edge geom attributes are found, the associated LineString geometries will also be converted.
Parameters
nx_multigraph
nx.MultiGraph
A networkX MultiGraph with x and y node attributes in the from_crs_code coordinate system. Optional geom edge attributes containing LineString geoms to be converted.
from_crs_code
int | str
An integer representing a valid EPSG code specifying the CRS from which the graph must be converted. For example, 4326 if converting data from an OpenStreetMap response.
to_crs_code
int | str
An integer representing a valid EPSG code specifying the CRS into which the graph must be projected. For example, 27700 if converting to British National Grid.
Returns
nx.MultiGraph
A networkX MultiGraph with x and y node attributes converted to the specified to_crs_code coordinate system. Edge geom attributes will also be converted if found.
nx_wgs_to_utm
nx_wgs_to_utm
(
nx_multigraph
:
networkx.classes.multigraph.MultiGraph
)->[
MultiGraph
]
Convert a graph from WGS84 geographic coordinates to UTM projected coordinates. Converts x and y node attributes from WGS84 lng, lat geographic coordinates to the local UTM projected coordinate system. If edge geom attributes are found, the associated LineString geometries will also be converted. The UTM zone derived from the first processed node will be used for the conversion of all other nodes and geometries contained in the graph. This ensures consistent behaviour in cases where a graph spans a UTM boundary.
Parameters
nx_multigraph
nx.MultiGraph
A networkX MultiGraph with x and y node attributes in the WGS84 coordinate system. Optional geom edge attributes containing LineString geoms to be converted.
Returns
nx.MultiGraph
A networkX MultiGraph with x and y node attributes converted to the local UTM coordinate system. If edge geom attributes are present, these will also be converted.
buffered_point_poly
buffered_point_poly
(
lng
:
float
lat
:
float
buffer
:
int
projected
:
bool = False
)->[
Polygon
int
]
Buffer a point and return a shapely Polygon. This function can be used to prepare a buffered point Polygon for passing to osm_graph_from_poly(). Expects WGS 84 / EPSG 4326 input coordinates. If projected is True then a UTM converted polygon will be returned. Otherwise returned as WGS 84 polygon in geographic coords.
Parameters
lng
float
The longitudinal WGS coordinate in degrees.
lat
float
The latitudinal WGS coordinate in degrees.
buffer
int
The buffer distance in metres.
projected
bool
Whether to project the returned polygon to a local UTM projected coordinate reference system.
Returns
geometry.Polygon
A shapely Polygon in WGS coordinates.
int
The UTM EPSG code.
fetch_osm_network
fetch_osm_network
(
osm_request
:
str
timeout
:
int = 300
max_tries
:
int = 3
)->[
Response | None
]
Fetches an OSM response.
This function requires a valid OSM request. If you prepare a polygonal extents then it may be easier to use
osm_graph_from_poly(), which would call this method on your behalf and then
builds a graph automatically.
Parameters
osm_request
str
A valid OSM request as a string. Use OSM Overpass for testing custom queries.
timeout
int
Timeout duration for API call in seconds.
max_tries
int
The number of attempts to fetch a response before raising.
Returns
requests.Response
An OSM API response.
osm_graph_from_poly
osm_graph_from_poly
(
poly_geom
:
shapely.geometry.polygon.Polygon
poly_crs_code
:
int | str = 4326
to_crs_code
:
int | str | None = None
custom_request
:
str | None = None
simplify
:
bool = True
contains_buffer_dist
:
int = 50
iron_edges
:
bool = True
remove_disconnected
:
int = 100
timeout
:
int = 300
max_tries
:
int = 3
)->[
MultiGraph
]
Prepares a networkX MultiGraph from an OSM request for the specified shapely polygon. This function will retrieve the OSM response and will automatically unpack this into a networkX graph. Simplification will be applied by default, but can be disabled.
Parameters
poly_geom
shapely.Polygon
A shapely Polygon representing the extents for which to fetch the OSM network.
poly_crs_code
int | str
to_crs_code
int | str
An optional integer representing a valid EPSG code for the generated network returned from this function. If this parameter is provided, then the network will be converted to the specified EPSG coordinate reference system. If not provided, then the OSM network will be projected into a local UTM coordinate reference system.
buffer_dist
int
A distance to use for buffering and cleaning operations. 15m by default.
custom_request
str
An optional custom OSM request. If provided, this must include a “geom_osm” string formatting key for inserting the geometry passed to the OSM API query. See the discussion below.
simplify
bool
Whether to automatically simplify the OSM graph.
contains_buffer_dist
int
The buffer distance to consider when checking if parallel edges sharing the same start and end nodes are sufficiently adjacent to be merged.
iron_edges
bool
Whether to iron the edges.
remove_disconnected
int
Remove disconnected components containing fewer nodes than specified. 100 nodes by default.
timeout
int
Timeout duration for API call in seconds.
max_tries
int
The number of attempts to fetch a response before raising.
Returns
nx.MultiGraph
A networkX MultiGraph with x and y node attributes that have been converted to UTM. The network will be simplified if the simplify parameter is True.
Notes
If you wish to provide your own OSM request, then provide a valid OSM API request to the custom_request parameter. The string must contain a geom_osm f-string formatting key. This allows for the geometry parameter passed to the OSM API to be injected into the request. It is also recommended to not use the skel output option so that cityseer can use street name and highway reference information for cleaning purposes. See OSM Overpass for experimenting with custom queries.
The following is the default query which you can adapt for your purposes. Notice the geom_osm f-string interpolation key (for injecting the geometry) and the use of out qt; instead of out skel qt;.
/* https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL */
[out:json];
(
way["highway"]
["area"!="yes"]
["highway"!~"bus_guideway|busway|escape|raceway|proposed|planned|abandoned|
platform|construction|emergency_bay|rest_area"]
["footway"!="sidewalk"]
["service"!~"parking_aisle|driveway|drive-through|slipway"]
["amenity"!~"charging_station|parking|fuel|motorcycle_parking|parking_entrance|parking_space"]
["indoor"!="yes"]
["level"!="-2"]
["level"!="-3"]
["level"!="-4"]
["level"!="-5"]
(poly:"{geom_osm}");
);
out body;
>;
out qt;
nx_from_osm
nx_from_osm
(
osm_json
:
str
)->[
MultiGraph
]
Generate a NetworkX MultiGraph from Open Street Map data.
Parameters
osm_json
str
A json string response from the OSM overpass API, consisting of nodes and ways.
Returns
nx.MultiGraph
A NetworkX MultiGraph with x and y attributes in WGS84 lng, lat geographic coordinates.
nx_from_osm_nx
nx_from_osm_nx
(
nx_multidigraph
node_attributes
:
list[str] | None = None
edge_attributes
:
list[str] | None = None
tolerance
:
float = 0.001
)->[
MultiGraph
]
Copy an OSMnx directed MultiDiGraph to an undirected cityseer MultiGraph. See the OSMnx section of the guide for a more general discussion (and example) on workflows combining OSMnx with cityseer.
x and y node attributes will be copied directly and geometry edge attributes will be copied to a geom edge attribute. The conversion process will snap the shapely LineString endpoints to the corresponding start and end node coordinates.
Note that OSMnx geometry attributes only exist for simplified edges: if a geometry edge attribute is not found, then a simple (straight) shapely LineString geometry will be inferred from the respective start and end nodes.
Other attributes will be ignored to avoid potential downstream misinterpretations of the attributes as a consequence of subsequent steps of graph manipulation, i.e. to avoid situations where attributes may fall out of lock-step with the state of the graph. If particular attributes need to be copied across, and assuming cognisance of downstream implications, then these can be manually specified by providing a list of node attributes keys per the node_attributes parameter or edge attribute keys per the edge_attributes parameter.
Parameters
nx_multidigraph
MultiDiGraph
A OSMnx derived networkX MultiDiGraph containing x and y node attributes, with optional geometry edge attributes containing LineString geoms (for simplified edges).
node_attributes
tuple[str]
Optional node attributes to copy to the new MultiGraph. (In addition to the default x and y attributes.)
edge_attributes
tuple[str]
Optional edge attributes to copy to the new MultiGraph. (In addition to the optional geometry attribute.)
tolerance
float
Tolerance at which to raise errors for mismatched geometry end-points vis-a-vis corresponding node coordinates. Prior to conversion, this method will check edge geometry end-points for alignment with the corresponding end-point nodes. Where these don’t align within the given tolerance an exception will be raised. Otherwise, if within the tolerance, the conversion function will snap the geometry end-points to the corresponding node coordinates so that downstream exceptions are not subsequently raised. It is preferable to minimise graph manipulation prior to conversion to a cityseer compatible MultiGraph otherwise particularly large tolerances may be required, and this may lead to some unexpected or undesirable effects due to aggressive snapping.
Returns
nx.MultiGraph
A cityseer compatible networkX graph with x and y node attributes and geom edge attributes.
nx_from_open_roads
nx_from_open_roads
(
open_roads_path
:
str | pathlib.Path
road_node_layer_key
:
str = 'road_node'
road_link_layer_key
:
str = 'road_link'
target_bbox
)->[
MultiGraph
]
Generates a networkX MultiGraph from an OS Open Roads dataset.
Parameters
open_roads_path
str | Path
A valid relative filepath from which to load the OS Open Roads dataset.
target_bbox
tuple[int]
A tuple of integers or floats representing the [s, w, n, e] bounding box extents for which to load the dataset. Set to None for no bounding box.
road_node_layer_key
str
The GPKG layer key for the OS Open Roads road nodes layer. This may change from time to time.
road_link_layer_key
str
The GPKG layer key for the OS Open Roads road links layer. This may change from time to time.
Returns
nx.MultiGraph
A cityseer compatible networkX graph with x and y node attributes and geom edge attributes.
network_structure_from_nx
network_structure_from_nx
(
nx_multigraph
:
networkx.classes.multigraph.MultiGraph
crs
:
str | int
)->[
GeoDataFrame
GeoDataFrame
NetworkStructure
]
Transpose a networkX MultiGraph into a gpd.GeoDataFrame and NetworkStructure for use by cityseer. Calculates length and angle attributes, as well as in and out bearings, and stores this information in the returned data maps.
Parameters
nx_multigraph
nx.MultiGraph
A networkX MultiGraph in a projected coordinate system, containing x and y node attributes, and geom edge attributes containing LineString geoms.
crs
str | int
CRS for initialising the returned structures. This is used for initialising the GeoPandas GeoDataFrame. # pylint: disable=line-too-long
Returns
gpd.GeoDataFrame
A gpd.GeoDataFrame with live, weight, and geometry attributes. The original networkX graph’s node keys will be used for the GeoDataFrame index. If nx_multigraph is a dual graph prepared with graphs.nx_to_dual then the corresponding primal edge LineString geometry will be set as the GeoPandas geometry for visualisation purposes using primal_edge for the column name. The dual node Point geometry will be saved in WKT format to the dual_node column.
gpd.GeoDataFrame
A gpd.GeoDataFrame with ns_edge_idx, start_ns_node_idx, end_ns_node_idx, edge_idx, nx_start_node_key ,nx_end_node_key, length, angle_sum, imp_factor, in_bearing, out_bearing, total_bearing, geom attributes.
rustalgos.NetworkStructure
A rustalgos.NetworkStructure instance.
network_structure_from_gpd
network_structure_from_gpd
(
nodes_gdf
:
geopandas.geodataframe.GeoDataFrame
edges_gdf
:
geopandas.geodataframe.GeoDataFrame
)->[
NetworkStructure
]
Reassembles a NetworkStructure from cityseer nodes and edges GeoDataFrames. This method is intended for use with “circular” workflows, where a cityseer NetworkX graph has been converted into cityseer nodes and edges GeoDataFrames using network_structure_from_nx. If the resultant GeoDataFrames are saved to disk and reloaded, then this method can be used to recreate the associated NetworkStructure which is required for optimised (rust) functions.
Parameters
nodes_gdf
gpd.GeoDataFrame
A cityseer created nodes gpd.GeoDataFrame where the originating networkX graph’s node keys have been saved as the DataFrame index, and where the columns contain x, y, live, and weight attributes.
edges_gdf
gpd.GeoDataFrame
A cityseer created edges gpd.GeoDataFrame with start_ns_node_idx, end_ns_node_idx, edge_idx, nx_start_node_key, nx_end_node_key, length, angle_sum, imp_factor, in_bearing, out_bearing attributes.
Returns
rustalgos.NetworkStructure
A rustalgos.NetworkStructure instance.
nx_from_cityseer_geopandas
nx_from_cityseer_geopandas
(
nodes_gdf
:
geopandas.geodataframe.GeoDataFrame
edges_gdf
:
geopandas.geodataframe.GeoDataFrame
)->[
MultiGraph
]
Write cityseer nodes and edges GeoDataFrames to a networkX MultiGraph. This method is intended for use with “circular” workflows, where a cityseer NetworkX graph has been converted into cityseer nodes and edges GeoDataFrames using network_structure_from_nx. Once metrics have been computed then this method can be used to convert the nodes and edges GeoDataFrames back into a cityseer compatible networkX graph with the computed metrics intact. This is useful when intending to visualise or export the metrics as a networkX graph.
If importing a generic gpd.GeoDataFrame LineString dataset, then use the nx_from_generic_geopandas instead.
Parameters
nodes_gdf
gpd.GeoDataFrame
A gpd.GeoDataFrame with live, weight, and Point geometry attributes. The index will be used for the returned networkX graph’s node keys.
edges_gdf
gpd.GeoDataFrame
An edges gpd.GeoDataFrame as derived from network_structure_from_nx.
Returns
nx.MultiGraph
A networkX graph with geometries and attributes as copied from the input GeoDataFrames.
geopandas_from_nx
geopandas_from_nx
(
nx_multigraph
:
networkx.classes.multigraph.MultiGraph
crs
:
str | int
)->[
GeoDataFrame
]
Transpose a cityseer networkX MultiGraph into a gpd.GeoDataFrame representing the network edges. Converts the geom attribute attached to each edge into a GeoPandas GeoDataFrame. This is useful when inspecting or cleaning the network in QGIS. It can then be reimported with nx_from_generic_geopandas
Parameters
nx_multigraph
nx.MultiGraph
A networkX MultiGraph in a projected coordinate system, containing x and y node attributes, and geom edge attributes containing LineString geoms.
crs
str | int
CRS for initialising the returned structures. This is used for initialising the GeoPandas GeoDataFrame. # pylint: disable=line-too-long
Returns
gpd.GeoDataFrame
A gpd.GeoDataFrame with edge_idx and geom attributes.
nx_from_generic_geopandas
nx_from_generic_geopandas
(
gdf_network
:
geopandas.geodataframe.GeoDataFrame
drop_self_loops_dist
:
int = 50
)->[
MultiGraph
]
Converts a generic LineString gpd.GeoDataFrame to a cityseer compatible networkX MultiGraph. The gpd.GeoDataFrame should be provided in the “primal” form, where edges represent LineString geometries.
Parameters
gdf_network
gpd.GeoDataFrame
A LineString gpd.GeoDataFrame.
drop_self_loops_dist
int
Drop looping street segments shorter than specified distance. 20m by default.
Returns
nx.MultiGraph
A cityseer compatible networkX graph with x and y node attributes and geom edge attributes.