mappymatch.maps.nx.readers.osm_readers

Functions

compress(g[, additional_metadata_keys])	Remove unnecessary data from a NetworkX graph while preserving essential attributes.
nx_graph_from_osmnx(geofence, network_type)	Download and process a road network from OpenStreetMap using OSMnx.
parse_osmnx_graph(graph, network_type[, xy, ...])	Process and clean a raw OSMnx graph for use with mappymatch.

Classes

NetworkType(value[, names, module, ...])

Enumeration of road network types supported by OSMnx for downloading from OpenStreetMap.

class mappymatch.maps.nx.readers.osm_readers.NetworkType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration of road network types supported by OSMnx for downloading from OpenStreetMap.

These network types determine which roads are included when downloading OSM data. Each type corresponds to a predefined filter in OSMnx for different use cases and transportation modes.

Values:

ALL_PRIVATE: All road types including private roads ALL: All public road types BIKE: Roads suitable for cycling DRIVE: Roads suitable for driving (excludes footpaths, bike paths, etc.) DRIVE_SERVICE: Driving roads including service roads (parking aisles, driveways, etc.) WALK: Roads suitable for walking (includes footpaths, pedestrian areas, etc.)

Examples:

>>> from mappymatch.maps.nx.readers.osm_readers import NetworkType
>>> # Download a driving network
>>> road_map = NxMap.from_geofence(geofence, network_type=NetworkType.DRIVE)
>>> # Download a walking network
>>> walk_map = NxMap.from_geofence(geofence, network_type=NetworkType.WALK)

ALL_PRIVATE = 'all_private'

ALL = 'all'

BIKE = 'bike'

DRIVE = 'drive'

DRIVE_SERVICE = 'drive_service'

WALK = 'walk'

mappymatch.maps.nx.readers.osm_readers.nx_graph_from_osmnx(geofence: Geofence, network_type: NetworkType, xy: bool = True, custom_filter: str | None = None, additional_metadata_keys: set | None = None, filter_to_largest_component: bool = True) → MultiDiGraph

Download and process a road network from OpenStreetMap using OSMnx.

This function: 1. Downloads OSM data within the geofence using OSMnx 2. Optionally projects to Web Mercator for accurate distances 3. Adds speed and travel time estimates 4. Converts distances to kilometers 5. Optionally filters to the largest connected component 6. Compresses the graph to remove unnecessary data

Args:

geofence: The geographic boundary for downloading. Must be in EPSG:4326 (lat/lon). network_type: The type of network to download (DRIVE, WALK, BIKE, etc.) xy: If True, project to Web Mercator (EPSG:3857) for accurate metric distances. If False, keep in lat/lon. Default is True. custom_filter: A custom OSMnx filter string for advanced queries (e.g., '["highway"~"motorway|trunk|primary"]'). If specified, overrides network_type. additional_metadata_keys: Set of OSM tag keys to preserve in road metadata (e.g., {'maxspeed', 'lanes', 'surface'}). filter_to_largest_component: If True (default), keep only the largest strongly connected component to ensure all parts of the network are routable to each other. If False, keep disconnected components (may cause routing failures).

Returns:

A processed NetworkX MultiDiGraph ready for use with NxMap

Raises:

MapException: If OSMnx is not installed

Examples:

>>> from mappymatch.maps.nx.readers.osm_readers import nx_graph_from_osmnx, NetworkType
>>>
>>> # Download a driving network
>>> graph = nx_graph_from_osmnx(
...     geofence=my_geofence,
...     network_type=NetworkType.DRIVE,
...     xy=True
... )
>>>
>>> # Download with custom filter and metadata
>>> graph = nx_graph_from_osmnx(
...     geofence=my_geofence,
...     network_type=NetworkType.DRIVE,
...     custom_filter='["highway"~"motorway|primary|secondary"]',
...     additional_metadata_keys={'maxspeed', 'lanes', 'name'}
... )

mappymatch.maps.nx.readers.osm_readers.parse_osmnx_graph(graph: MultiDiGraph, network_type: NetworkType, xy: bool = True, additional_metadata_keys: set | None = None, filter_to_largest_component: bool = True) → MultiDiGraph

Process and clean a raw OSMnx graph for use with mappymatch.

This function takes a graph downloaded from OSMnx and processes it by: - Projecting to a metric coordinate system (optional) - Computing edge speeds and travel times - Adding distance in kilometers - Filtering to the largest connected component (optional) - Creating geometries for edges that lack them - Compressing by removing unnecessary data

Args:

graph: A raw NetworkX MultiDiGraph from OSMnx network_type: The type of network (used for metadata) xy: If True, project to Web Mercator (EPSG:3857). If False, keep in lat/lon. additional_metadata_keys: Set of OSM tag keys to preserve in road metadata filter_to_largest_component: If True, keep only the largest strongly connected component. If False, keep all components.

Returns:

A cleaned and processed NetworkX MultiDiGraph ready for NxMap

Raises:

MapException: If OSMnx is not installed or if the network has no connected components

mappymatch.maps.nx.readers.osm_readers.compress(g: MultiDiGraph, additional_metadata_keys: set | None = None) → MultiDiGraph

Remove unnecessary data from a NetworkX graph while preserving essential attributes.

This function reduces memory usage and file size by: - Moving specified OSM tags to a metadata dictionary - Removing edge attributes that aren't needed for routing or matching - Removing all node attributes (only the node IDs are needed)

Essential attributes for edges are preserved: - geometry: The LineString geometry of the road - kilometers: Distance in kilometers for routing - travel_time: Estimated travel time for routing - metadata: Dictionary of additional OSM tags

Args:

g: The NetworkX MultiDiGraph to compress additional_metadata_keys: Set of OSM tag keys to preserve in the metadata dictionary. Default preserved keys are 'osmid' and 'name'. Any additional keys specified here will also be moved to metadata.

Returns:

The compressed NetworkX MultiDiGraph (modified in-place and returned)

Examples:

>>> # Compress with default metadata
>>> compressed = compress(graph)
>>>
>>> # Preserve additional OSM tags
>>> compressed = compress(
...     graph,
...     additional_metadata_keys={'maxspeed', 'lanes', 'surface', 'highway'}
... )
>>>
>>> # Access metadata
>>> edge_data = graph.edges[('123', '456', 0)]
>>> print(edge_data['metadata']['name'])  # Street name
>>> print(edge_data['metadata']['maxspeed'])  # Speed limit if available