Quick Start¶
In this section, some examples are provided to demonstrate how to use osm2gmns to generate, manipulate and output networks.
Download OSM Data¶
To reduce uncertainties while directly parsing network data from the osm server via APIs, osm2gmns uses downloaded osm files to extract useful network information. As a result, the first step is preparing osm files.
Thanks to the open-source nature of OpenStreetMap, there are lots of APIs and mirror sites that we can use to download osm map data. We list several popular sites here for users to choose.
OpenStreetMap Homepage
On OpenStreetMap homepage, click the Export
button to enter Export mode. Before downloading,
you may need to span and zoom in/out the map to make sure that your target area is properly shown on the screen.
Or, you can use Manually select a different area
to select your area more precisely. Click the Export
button in blue to export the network you want.
Note that if the target area is too large, you may get an error message: “You requested too many nodes
(limit is 50000). Either request a smaller area, or use planet.osm”. In this case, you can always click
Overpass API
to download the network you need via a mirror site.
Geofabrik
Different from the way of downloading map data from OpenStreetMap homepage, Geofabrik enables you to download network data for administrative areas. On OpenStreetMap homepage, we can only download areas defined by rectangles. In Geofabrik, you can click the corresponding quick link of your interested region to download the map data you need. You can always click the name of regions to check if sub region data are available.
Generally, there are three types of file format for users to choose when downloading map data.
osm2gmns supports .pbf
and .osm
files. In osm2gmns, networks stored in .osm
files
are parsed quickly than those stored in .pbf
files. However, compared with .pbf
files,
.osm
files take much more hard disk space to store networks and much more space in RAM while parsing.
BBBike
If your target area is neither an administrative region nor a rectangle, BBBike may be a good choice. BBBike enables you to select your region using a polygon. BBBike supports numerous file formats to output and store network data. Users can select a proper one according to their requirements.
Parse OSM Data¶
We use the region around Arizona State University, Tempe Campus in this guide to introduce some major functions in osm2gmns.
Obtain a transportation network from an osm file.
>>> import osm2gmns as og
>>> net = og.getNetFromOSMFile('asu.osm')
>>> # we recommend using getNetFromPBFFile() for large networks
>>> # net = og.getNetFromPBFFile('***.osm.pbf')
Note
getNetFromPBFFile()
is supported in release (0.2.0) or later.
A link will be included in the network file from osm database if part of the link lies in the region
that users selected. If argument strict_mode
(default: True
) is set as True
, link segments that
outside the region will be cut off when parsing osm data. If argument strict_mode
is set as False
,
all links in the network file will be imported.
One loaded network may contain several sub networks, with some sub networks are not accessible from others.
In most cases, these sub networks include a large sub network and some isolated nodes or links. When the
number of nodes of a sub network is less than argument min_nodes
(default: 1
), this sub network
will be discarded.
Users can use argument combine
(default: False
) to control short link combinations. If combine
is enabled, two-degree nodes (one incoming link and one outgoing link) will be removed, and two adjacent
links will be combined to generate a new link.
Noticed that most links do not have “lanes” information in the map data provided by OpenStreetMap. Thus,
we use a default lanes dictionary for each link type in osm2gmns. By setting default_lanes
(default: False
)
as True
, the default value will be assigned to a link if it does not come with “lanes” information. The
default dictionary in osm2gmns:
default_lanes_dict = {'motorway': 4, 'trunk': 3, 'primary': 3, 'secondary': 2, 'tertiary': 2,
'residential': 1, 'service': 1, 'cycleway':1, 'footway':1, 'track':1,
'unclassified': 1, 'connector': 2}
default_speed_dict = {'motorway': 59, 'trunk': 39, 'primary': 39, 'secondary': 39, 'tertiary': 29,
'residential': 29, 'service': 29, 'cycleway':9, 'footway':4, 'track':29,
'unclassified': 29, 'connector':59}
default_lanes
also accepts a dictionary. In that case, osm2gmns will use the dictionary provided by users
to update the default dictionary.
A similar fashion applies for argument default_speed
.
Output Networks to CSV¶
Based on the net
instance obtained from the last step, outputNetToCSV
can be used to output the parsed network
to CSV files.
>>> og.outputNetToCSV(net)
Users can use argument output_folder
to specify the folder to store output files. Node information will be
written to node.csv
, while link information will be written to link.csv
.
If argument combine
is set as True
when parsing the network, segment.csv
will also be created to
store lane changes in links. Lane changes occur when combining two adjacent links with different lanes in the
combination step.
Consolidate Intersections¶
In OpenStreetMap, one large intersection is often represented by multiple nodes. This structure brings some difficulties when conducting traffic simulations (hard to model traffic signals in these intersections). osm2gmns enables users to consolidate intersections while parsing networks, i.e., generate a new node to replace existing nodes for each large intersection.
>>> net = og.getNetFromOSMFile('asu.osm')
>>> og.consolidateComplexIntersections(net)
>>> og.outputNetToCSV(net)
When executing function getNetFromOSMFile
, osm2gmns will automatically identify complex intersections based
on the argument int_buffer
(defalut: 20.0
). Nodes that belong to one complex intersection will be assigned
with the same main_node_id
, but these nodes will not be consolidated into one node unless function
consolidateComplexIntersections
is called.
Users can also check and revise complex intersection identification results first, then conduct the consolidating operation to obtain more reasonable outcomes.
>>> net = og.getNetFromOSMFile('asu.osm')
>>> og.outputNetToCSV(net)
>>> # check the main_node_id column in node.csv
>>> net = og.getNetFromCSV()
>>> og.consolidateComplexIntersections(net)
>>> og.outputNetToCSV(net, output_folder='consolidated')
Network Types and POI¶
osm2gmns supports five different network types, including auto
, bike
, walk
, railway
, aeroway
.
Extract the auto and railway network from an osm file by setting network_type
(default: (auto,)
) as
(auto,railway)
:
>>> net = og.getNetFromOSMFile('asu.osm', network_type=('auto','railway','aeroway'))
Obtain POIs (Point of Interest) from osm map data.
>>> net = og.getNetFromOSMFile('asu.osm', POIs=True)
If POIs
(default: False
) is set as True
, a file named poi.csv
will be generated when outputting
a network using function outputNetToCSV
.
Connect POIs with transportation network.
>>> net = og.getNetFromOSMFile('asu.osm', POIs=True)
>>> og.connectPOIWithNet(net)
By using function connectPOIWithNet
, a node located at the centroid of each POI will be generated to
represent the POI, then connector links will be built to connect the POI node with the nearest node in the
transportation network.