Public API

osm2gmns.getNetFromFile(filepath, mode_types='auto', link_types=[], connector_link_types=[], POI=False, POI_sampling_ratio=1.0, osm_node_attributes=[], osm_link_attributes=[], osm_poi_attributes=[], strict_boundary=True)

Parses an OpenStreetMap file and creates a transportation network object.

Parameters:

filepath (str) – Path to the input OSM file (.osm, .xml, or .pbf format).
mode_types (str or list of str) – Specifies the transportation modes to include. Options: ‘auto’, ‘bike’, ‘walk’, ‘railway’, ‘aeroway’. Can be a single string or a list of strings.
link_types (str or list of str) – Filters the network to include only specified OSM link types. If empty, all relevant link types for the selected mode_types are included. Supported types include: ‘motorway’, ‘trunk’, ‘primary’, ‘secondary’, ‘tertiary’, ‘residential’, ‘service’, ‘cycleway’, ‘footway’, ‘track’, ‘unclassified’, ‘connector’, ‘railway’, ‘aeroway’.
connector_link_types (str or list of str) – Specifies link types that should only be included if they connect directly to links included via link_types. Useful for connecting main networks to specific areas (e.g., for traffic zones). Same supported types as link_types. If empty, no connector links are specifically handled this way.
POI (bool) – If True, extracts Points of Interest (POIs) from the OSM data.
POI_sampling_ratio (float) – Fraction of POIs to extract if POI is True. Must be between 0.0 and 1.0.
osm_node_attributes (str or list of str) – List of additional OSM tag keys whose values should be extracted as attributes for nodes. If empty, only default attributes are extracted.
osm_link_attributes (str or list of str) – List of additional OSM tag keys whose values should be extracted as attributes for links. If empty, only default attributes are extracted.
osm_poi_attributes (str or list of str) – List of additional OSM tag keys whose values should be extracted as attributes for POIs. If empty, only default attributes are extracted.
strict_boundary (bool) – If True, clips links that cross the boundary of the downloaded OSM region. If False, includes the full geometry of any link that partially falls within the region.

Returns:

An osm2gmns Network object containing the parsed transportation network data.

Return type:

Network

osm2gmns.outputNetToCSV(network, output_folder='')

Exports the network object data to CSV files in GMNS format.

Writes network information into separate CSV files (node.csv, link.csv, poi.csv) adhering to the General Modeling Network Specification (GMNS).

Parameters:

network (Network) – The osm2gmns Network object containing the data to be exported.
output_folder (str) – The directory path where the CSV files will be saved. If empty or not provided, defaults to the current working directory.

Returns:

Creates CSV files in the specified output folder.

Return type:

None

osm2gmns.consolidateComplexIntersections(network, auto_identify=False, intersection_filepath=None, int_buffer=20.0)

Consolidates multiple OSM nodes representing a single complex intersection into one node.

Simplifies network topology by merging nodes that form complex junctions, often found at large, signalized intersections in OSM data. Consolidation can be based on (1) automatic detection, (2) an external file defining intersections, or (3) pre-assigned ‘intersection_id’ attributes in nodes (if network is loaded from CSV, nodes with the same ‘intersection_id’ will be considered as belonging to the same complex intersection).

Priority for defining intersections: (3) Pre-existing ‘intersection_id’ in nodes, (2) intersection_filepath, (1) auto_identify.

Parameters:

network (Network) – The osm2gmns Network object to modify.
auto_identify (bool) – If True, attempts to automatically identify complex intersections based on built-in rules: nodes must have ‘ctrl_type’ = ‘signal’ and be connected by a link shorter than or equal to int_buffer.
intersection_filepath (str or None) – Path to a CSV file defining complex intersections. Required columns: ‘x_coord’, ‘y_coord’ (defining the intersection center). Optional column: ‘int_buffer’ (overrides the global int_buffer for that specific intersection). Nodes within the buffer distance of a defined center will be consolidated.
int_buffer (float) – The distance threshold (in meters) used for consolidation. Applied globally if auto_identify is True, or per-intersection if not specified in the intersection_filepath.

Returns:

Modifies the input network object in place.

Return type:

None

osm2gmns.fillLinkAttributesWithDefaultValues(network, default_lanes=False, default_lanes_dict={}, default_speed=False, default_speed_dict={}, default_capacity=False, default_capacity_dict={})

Assigns default values to link attributes (lanes, speed, capacity) if they are missing.

Populates essential link attributes based on ‘link_type’ for links where this information wasn’t available in the source OSM data. Users can rely on built-in defaults or provide dictionaries to override them for specific link types.

Parameters:

network (Network) – The osm2gmns Network object to modify.
default_lanes (bool) – If True, assign default lane counts to links missing this attribute.
default_lanes_dict (dict) – A dictionary mapping link types (str) to default lane counts (int). Overrides built-in defaults for the specified link types. Example: {‘motorway’: 3, ‘primary’: 3}.
default_speed (bool) – If True, assign default speed limits (km/h) to links missing this attribute.
default_speed_dict (dict) – A dictionary mapping link types (str) to default speed limits (float). Overrides built-in defaults. Example: {‘residential’: 20.0}.
default_capacity (bool) – If True, assign default capacities (vehicles per hour per lane) to links missing this attribute.
default_capacity_dict (dict) – A dictionary mapping link types (str) to default capacities (int). Overrides built-in defaults. Example: {‘primary’: 1800}.

Returns:

Modifies the input network object in place by adding or updating link attributes.

Return type:

None

osm2gmns.generateNodeActivityInfo(network, zone_filepath=None)

Generates activity_type, is_boundary, zone_id for nodes in the network.

Analyzes the network topology to assign relevant attributes to nodes, useful for transportation modeling. ‘activity_type’ (e.g., ‘motorway’, ‘residential’) is inferred from adjacent links. ‘is_boundary’ indicates if a node is at the edge of the defined network area. ‘zone_id’ assigns nodes to traffic analysis zones (TAZs).

Parameters:

network (Network) – The osm2gmns Network object to modify.
zone_filepath (str or None) – Path to a zone definition file (CSV). If provided, ‘zone_id’ for boundary nodes is determined based on this file. Otherwise, the ‘node_id’ is used as the ‘zone_id’ for boundary nodes. Expected CSV fields: “zone_id”, “x_coord”, “y_coord”, “geometry”. ‘geometry’ should be in WKT format (POINT, POLYGON, or MULTIPOLYGON). ‘x_coord’ and ‘y_coord’ can alternatively define POINT geometry. Boundary nodes are assigned the ‘zone_id’ of the containing polygon/multipolygon, or the nearest point zone if not within any polygon.

Returns:

Modifies the input network object in place by adding or updating node attributes.

Return type:

None

osm2gmns.downloadOSMData(area_id, output_filepath='map.osm', url='www.overpass-api.de/api/interpreter')

Downloads OpenStreetMap (OSM) data for a specified region using the Overpass API.

This function queries the Overpass API for a given OSM relation ID, retrieves the corresponding map data, and saves it to a local file.

Parameters:

area_id (int) – The OpenStreetMap relation ID for the area of interest. See the ‘Get OSM Data’ section in the user guide for details on finding relation IDs.
output_filepath (str) – The desired filepath for the downloaded OSM data. If no extension or an unsupported extension is provided, ‘.osm’ will be used. Supported extensions: ‘.osm’, ‘.xml’.
url (str) – The URL of the Overpass API endpoint.

Returns:

The function saves the data to the specified file and prints status messages to the console.

Return type:

None