Functions

osm2gmns.osmnet

osm2gmns.osmnet.build_net.getNetFromFile(filename='map.osm', network_types=('auto',), link_types='all', POI=False, POI_sampling_ratio=1.0, strict_mode=True, offset='no', min_nodes=1, combine=False, bbox=None, default_lanes=False, default_speed=False, default_capacity=False, start_node_id=0, start_link_id=0)

Get an osm2gmns Network object from an osm file

Parameters:
  • filename (str) – path of an osm file; can be absolute or relative path; supported osm file formats: .osm, .xml, and .pbf

  • network_types (str, tuple of strings, list of strings, or set of strings) – osm2gmns supports five different network types, including auto, bike, walk, railway, and aeroway. network_types can be any one or any combinations of the five supported network types

  • link_types (str, tuple of strings, list of strings, or set of strings) – supported link types: motorway, trunk, primary, secondary, tertiary, residential, service, cycleway, footway, track, unclassified, connector, railway, and aeroway.

  • POI (bool) – if extract point of interest information

  • POI_sampling_ratio (float) – prcentage of POIs to be extracted if POI is set as True. this value should be a float number between 0.0 and 1.0.

  • strict_mode (bool) – if True, network elements (node, link, poi) outside the boundary will be discarded

  • offset (str) – offset overlapping links. the value of this argument can be ‘left’, ‘right’, or ‘no’

  • min_nodes (int) – a network return by the function may contain several sub-networks that are disconnected from each other. sub-networks with the number of nodes less than min_nodes will be discarded

  • combine (bool) – if True, adjacent short links with the same attributes will be combined into a long link. the operation will only be performed on short links connected with a two-degree nodes (one incoming link and one outgoing link)

  • bbox (tuple of four float/int values, list of four float/int values, None) – specify the boundary of the network to be extracted, consisting of minimum latitude, minimum longtitude, maximum latitude, and maximum longitud. if None, osm2gmns will try to find network boundary from the input osm file

  • default_lanes (bool, dict) – if True, assign a default value for links without lanes information based on built-in settings. if a dict, assign a default value for links without lanes information based on the dict passed by users.

  • default_speed (bool, dict) – if True, assign a default value for links without speed information based on built-in settings. if a dict, assign a default value for links without speed information based on the dict passed by users.

  • default_capacity (bool, dict) – if True, assign a default value for links without capacity information based on built-in settings. if a dict, assign a default value for links without capacity information based on the dict passed by users.

  • start_node_id (int) – osm2gmns assigns node_ids to generated nodes starting from start_node_id.

  • start_link_id (int) – osm2gmns assigns link_ids to generated links starting from start_link_id

Returns:

network – osm2gmns Network object

Return type:

Network

osm2gmns.osmnet.complex_intersection.consolidateComplexIntersections(network, auto_identify=False, intersection_file=None, int_buffer=20.0)

Consolidate each complex intersection that are originally represented by multiple nodes in osm into one node. Nodes with the same intersection_id will be consolidated into one node. intersection_id of nodes can be obtained in three ways.

(1) set the argument auto_identify as True, then osm2gmns will automatically identify complex intersections and assign intersection_id for corresponding nodes.

  1. provide an intersection file that specifies the central position (required) and buffer (optional) of each complex intersection.

  2. user can assign intersection_id to nodes manually in network csv files (node.csv), and load the network using function loadNetFromCSV provided by osm2gmns.

The priority of the three approaches is (3) > (2) > (1). Rules used in the approach (1) to identify if two nodes belong to a complex intersection: (a) ctrl_type of the two nodes must be signal; (b) there is a link connecting these two nodes, and the length of the link is shorter than or equal to the argument int_buffer.

Parameters:
  • network (Network) – osm2gmns Network object

  • auto_identify (bool) – if automatically identify complex intersections using built-in methods in osm2gmns. nodes that belong to a complex intersection will be assigned with the same intersection_id

  • intersection_file (str) – path of an intersction csv file that specifies complex intersections. required fields: central position of intersections (in the form of x_coord and y_coord); optional field: int_buffer (if not specified, the global int_buffer will be used, i.e., the forth arugment). For each record in the intersection_file, osm2gmns consolidates all nodes with a distance to the central position shorter than buffer.

  • int_buffer (float) – the threshold used to check if two nodes belong to one complex intersection. the unit is meter

Return type:

None

Combine links connected by two-degree nodes into a longer link

Parameters:

network (Network) – osm2gmns Network object

Return type:

None

osm2gmns.osmnet.enrich_net_info.generateNodeActivityInfo(network, zone_file=None)

Generate activity information, including activity_type, is_boundary, zone_id for nodes. activity_type includes motorway, primary, secondary, tertiary, residential, etc, and is determined by adjacent links, If a zone_file is provided, zone_id of boundary nodes will be determined by zones defined in the zone_file. Otherwise, for each boundary node, its node_id will be used as zone_id.

Parameters:
  • network (Network) – osm2gmns Network object

  • zone_file (str, None) – filename of the zone file. optional

Return type:

None

osm2gmns.osmnet.enrich_net_info.generateLinkVDFInfo(network)

Generate VDF information, including VDF_fftt1 and VDF_cap1 for links. The unit of VDF_fftt1 and VDF_cap1 are min and veh/hour/link, respectively

Parameters:

network (Network) – osm2gmns Network object

Return type:

None

osm2gmns.osmnet.pois.connectPOIWithNet(network)

Connect POIs with the traffic network. Specifically, for each POI, osm2gmns will build a bi-directional connector to connect the POI with its nearest node in the traffic network

Parameters:

network (Network) – an osm2gmns Network object

Return type:

None

osm2gmns.osmnet.visualization.show(network, save=False, figsize=None)

Show the network in a pop-up window

Parameters:
  • network (Network) – an osm2gmns Network object

  • save (bool) – if True, the plot will also be saved to a local file named network.jpg

  • figsize (tuple of int/float, list of int/float) – size of the figure

Return type:

None

osm2gmns.osmnet.visualization.saveFig(network, picpath='network.jpg', figsize=None)

Save the network plot to a local file

Parameters:
  • network (Network) – an osm2gmns Network object

  • picpath (str) – path to store to network plot. can be an absolute or a relative path

  • figsize (tuple of int/float, list of int/float) – size of the figure

Return type:

None

osm2gmns.io

osm2gmns.io.load_from_csv.loadNetFromCSV(folder='', node_file=None, link_file=None, movement_file=None, segment_file=None, geometry_file=None, POI_file=None, coordinate_type='lonlat', enconding=None)

Load a network from csv files in GMNS format

Parameters:
  • folder (str) – the folder where network files are stored

  • node_file (str) – filename of the node file. required

  • link_file (str) – filename of the link file. required

  • movement_file (str, None) – filename of the movement file. optional

  • segment_file (str, None) – filename of the segment file. optional

  • geometry_file (str, None) – filename of the geometry file. optional

  • POI_file (str, None) – filename of the POI file. optional

  • coordinate_type (str) – the coordinate system used by the network to be loaded. can be lonlat, meter, feet

  • enconding (str, None) – the encoding used by the network files. if None, osm2gmns will use the default encoding of the local operating system

Returns:

network – an osm2gmns Network object

Return type:

Network

osm2gmns.io.downloader.downloadOSMData(area_id, output_filename='map.osm', url='www.overpass-api.de/api/interpreter')

Download OpenStreetMap data via overpass API

Parameters:
  • area_id (int) – relation_id of the area of interest

  • output_filename (int) – full path where the downloaded network will be stored

  • url (int) – OpenStreetMap API url

Return type:

None

osm2gmns.io.writefile.outputNetToCSV(network, output_folder='', prefix='', projection=False, encoding=None)

Output an osm2gmns network object to csv files in GMNS format

Parameters:
  • network (Network) – an osm2gmns network object

  • output_folder (str) – path of the folder to store network files. can be an absolute or a relative path

  • prefix (str) – prefix of output csv files

  • projection (bool) – if True, osm2gmns will project the network to a local coordinate system when ouptting a network

  • encoding (str) – the file encoding used to output a network

Return type:

None

osm2gmns.movement

osm2gmns.movement.generate_movements.generateMovements(network)

Use osm2gmns built-in methods to generate movements for each node (intersection) in a network

Parameters:

network (Network) – an osm2gmns Network object

Return type:

None

osm2gmns.multiresolutionnet

osm2gmns.multiresolutionnet.build_mrnet.buildMultiResolutionNets(macronet, generate_micro_net=True, auto_movement_generation=True, exclusive_bike_walk_lanes=True, connector_type=None, width_of_lane=3.5, length_of_cell=7.0)

Build the corresponding mesoscopic and microscopic networks for a source (macroscopic) network

Parameters:
  • macronet (Network) – a soucrce osm2gmns Network object

  • generate_micro_net (bool) – True: generate meso and micro networks; False: only generate meso network

  • auto_movement_generation (bool) – automatically generate movements for intersections without movement information by calling function generateMovements in osm2gmns. if auto_movement_generation is set as False, movements at intersections without movement information will not be generated

  • exclusive_bike_walk_lanes (bool) – build exclusive lanes for bike and walk

  • connector_type (int) – link_type of connectors

  • width_of_lane (float) – width of lanes in meter

  • length_of_cell (float) – lenght of cells in meter

Return type:

None

osm2gmns.func_lib

osm2gmns.func_lib.getOSMRelationID(poi_name: str) float | None

Get the relation id of a place of interest globally

Parameters:

poi_name (str) – the name of the place of interest, e.g., “Arizona State University” e.g., “Tempe, Arizona, USA” e.g., “Arizona, USA”

Returns:

the relation id of the place of interest, if not found, return None

Return type:

Union[float, None]

Example

>>> import osm2gmns as og
>>> rel = og.getOSMRelationID("Arizona State University")
>>> rel
    Info: Found relation id 3444656 from web
    Info: location of the place of interest:
    {
        "place_id": 318528634,
        "licence": "Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright",
        "osm_type": "relation",
        "osm_id": 3444656,
        "lat": "33.4213174",
        "lon": "-111.93316305413154",
        "class": "amenity",
        "type": "university",
        "place_rank": 30,
        "importance": 0.5547365758311374,
        "addresstype": "amenity",
        "name": "Arizona State University",
        "display_name": "Arizona State University, 1151, South Forest Avenue, Tempe Junction, Tempe, Maricopa County, Arizona, 85281, United States",
        "boundingbox": [
            "33.4102062",
            "33.4329786",
            "-111.9411651",
            "-111.9092447"
        ]
    }
3444656