User Manual

OpenStreetMap Functions for MATLAB v.0.2

Ioannis F. Filippidis

Control Systems LabDepartment of Mechanical EngineeringNational Technical University of Athens

Athens,Greece

jfilippidis@gmail.comDate: May 3, 2012

2

Cover: Map data plot for the port of Piraeus, Greece. Map data © OpenStreetMapcontributors, CC-BY-SA.

Copyright © 2010 by Ioannis F. Filippidis.All Rights Reserved.

This work has been typeset by the author using XƎTEX & friends.

Graphics which are not courtesy of the author reference the source in their caption.MATLAB® is a registered trademark of The Mathworks, Inc.OpenStreetMap is a registered trademark of Steve Coast.The OpenStreetMap logo is a registered trademark of the OpenStreetMap Foundation.

Chapter 1

Usage

1.1 IntroductionThis is a small set of functions to import data from an OpenStreetMap XML Data File

into MATLAB. The XML format is first loaded into MATLAB and then a parsing scriptextracts part of the information contained in the file. This is saved in a MATLAB structure.Then, it can be used to plot the transportation network and to extract its connectivitymatrix, as well as to identify its unique nodes. An example of using these functions can befound in the file usage_example.m. The software architecture is shown in Fig. 1.1.

1.1.1 DependenciesThis software requires the following functions, which can be downloaded from the Math-

works central File Exchange and are copyright of their authors, under the BSD license.

1. xml2struct file id 28518 ©2010 by Wouter Falkena.

2. lat_lon_proportions file id 32462 ©2011 by Jonathan Sullivan.

3. dijkstra file id 24134 ©2008-2009 Stanford University, by David F. Gleich.

For the user’s convenience, these functions have also been included in the distribution of thissoftware, together with their respective licenses.

Remark: Please put these functions in your MATLAB path. You can do this byadding the xml2struct directory (after extracting from the archive) to your MATLAB path(pathtool command in MATLAB).

1.2 Parse the OpenStreetMap fileTo parse an OpenStreetMap XML file (OSM XML) use the function parse_openstreetmap,

by issuing the command parsed_osm = parse_openstreetmap(openstreetmap_filename).This will parse an OSM XML file downloaded from the OpenStreetMap website. The OSMfilename is provided as the string argument openstreetmap_filename. This function returnsa MATLAB structure parsed_osm containing a subset of the OSM data sufficient to extractthe transportation network connectivity. The structure’s fields are shown schematically inFig. 1.3.

To download an OpenStreetMap XML Data file, navigate tohttp://www.openstreetmap.org/

4 Usage

plot_way.m

load_osm_xml.m

parse_osm.m

extract_connectivity.m

parse_openstreetmap.m

xml2struct.m(c) 2010, Wouter Falkena

assign_from_parsed.m

get_way_tag_key.m

get_unique_node_xy.m

show_map.m

route_planner.m

plot_road_network.m

plot_route.m

plot_nodes.m

Figure 1.1: Software architecture.

penStreetMap(a) OpenStreetMap logo (®by Steve Coast from theOpenStreetMap wiki).

(b) Aerial photography for mapping the Praga district ofWarsaw (CC BY-SA by Balrog, via OpenStreetMap wiki).

(c) GPS Mapping of Strasbourgon bicycle. (CC BY-2.0 by fran-cois, via Wikimedia Commons).

Figure 1.2: OpenStreetMap

1.3 Plot the map 5

.osm

bounds

node

way

relation

lat, lon, ...

nd, tag, ...

Figure 1.3: OpenStreetMap MATLAB structure fields.

23.62 23.625 23.63 23.635 23.64 23.645 23.65 23.655 23.66 23.665 23.6737.925

37.93

37.935

37.94

37.945

37.95

Longitude (o)

Latitu

de (

o)

OpenStreetMap osm file

(a) Without an underlying image. (b) With an underlying image.

Figure 1.4: Examples of plotting the loaded OSM data using plot_way. Map data © Open-StreetMap contributors, CC-BY-SA.

and after zooming in the area of interest, export its data using the Export option to save itas an OpenStreetMap XML Data file, selecting this from the Format to Export options.

1.3 Plot the mapTo plot the parsed OSM file, using the MATLAB structure obtained in the previous

section, use the function plot_way(ax, parsed_osm, map_img_filename). Argument axis a handle to an axes object. parsed_osm is the MATLAB structure object returned by theparsing function parse_openstreetmap. Optionally, the last argument, map_img_filename,is a (raster) picture to load and plot underneath the transportation network of the map.Examples of the result with and without the underlying image are shown in Fig. 1.4a andFig. 1.4b, respectively.

The other plotting functions are plot_nodes, plot_road_network and plot_route.Function plot_nodes can be used to plot selected (or all) nodes and optionally their IDsas text labels, as shown in Fig. 1.5c. Function plot_road_network plots the nodes and edgesconnecting them, as determined by the connectivity matrix created using extract_connectivity(see section 1.4), as shown in Fig. 1.5d. Function plot_route plots the series of nodestraversed along a route found by the route_planner function, as shown in Fig. 1.7a andFig. 1.7b.

1.4 Extract road connectivity and RoutingTo extract the road connectivity from the OSM data loaded into the MATLAB structure,

use the function extract_connectivity. This function extracts the connectivity of the road

6 Usage

8.924 8.926 8.928 8.93 8.932 8.934 8.936 8.938

44.402

44.404

44.406

44.408

44.41

44.412

44.414

Longitude (o)

La

titu

de

(o)

OpenStreetMap osm file

(a) plot_way without an underlying image.

8.924 8.926 8.928 8.93 8.932 8.934 8.936 8.938

44.402

44.404

44.406

44.408

44.41

44.412

44.414

Longitude (o)

La

titu

de

(o)

OpenStreetMap osm file

(b) plot_way with an underlying image.

8.924 8.926 8.928 8.93 8.932 8.934 8.936 8.938

44.402

44.404

44.406

44.408

44.41

44.412

44.414

Longitude (o)

Latitu

de (

o)

OpenStreetMap osm file

index=1

index=11

index=31index=51

index=61

index=71

index=81

index=91

index=101

index=111

index=131

index=141

index=151

index=281

index=291

index=301

index=331

index=441

index=451index=461

index=471

index=491

index=521

index=531

index=561

index=581

index=611

index=621

index=631

index=641index=651

index=661

index=671

index=681

index=691

index=701

index=711

index=721

index=731

index=741

index=751

index=761

index=771

index=781

index=791index=801

index=811

index=821

index=831

index=851

index=861

index=871

index=881

index=891

index=901

index=911

index=921

index=941

index=951

index=961

index=971

index=981index=991

(c) plot_nodes.

8.924 8.926 8.928 8.93 8.932 8.934 8.936 8.938

44.402

44.404

44.406

44.408

44.41

44.412

44.414

Longitude (o)

Latitu

de (

o)

OpenStreetMap osm file

(d) plot_road_network.

Figure 1.5: Examples of plotting the loaded OSM data. Map data © OpenStreetMapcontributors, CC-BY-SA.

1.4 Extract road connectivity and Routing 7

0 1000 2000 3000 4000 5000 6000

0

1000

2000

3000

4000

5000

6000

nz = 15204

Figure 1.6: Connectivity matrix of transportation network of Piraeus (nodes are not unique),corresponding to Fig. 1.4a. Observe the sparsity of the adjacency matrix.

network of the OpenStreetMap file. This yields a set of nodes where the roads intersect.Some intersections may appear multiple times, because different roads may meet at the sameintersection and because multiple directions are considered different roads. For this reason,in addition to the connectivity matrix, the unique nodes are also identified.

To call it, issue the command:[connectivity_matrix, intersection_nodes] = extract_connectivity(parsed_osm).The input parsed_osm is the MATLAB structure returned by function parse_openstreetmap.This function returns the network’s adjacency matrix in connectivity_matrix and theunique nodes corresponding to the intersections of the network in intersection_nodes.

Routing can be performed based on the extracted adjacency matrix. The function per-forming routing is route_planner. It can be called by issuing[route, dist] = route_planner(dg, start, target), where dg is the adjacency matrix ofthe directed graph representing the transportation network (that is, the connectivity_matrixabove), start is the source node and target the destination node. This function returnsroute, which is a matrix of traversed node indices, and dist, which is the count of nodestraversed (and not the spatial distance over the map). Plotted examples are shown inFig. 1.7a and Fig. 1.7b.

8 Usage

8.924 8.926 8.928 8.93 8.932 8.934 8.936 8.938

44.402

44.404

44.406

44.408

44.41

44.412

44.414

Longitude (o)

Latitu

de (

o)

OpenStreetMap osm file

(a) Without an underlying image.

8.924 8.926 8.928 8.93 8.932 8.934 8.936 8.938

44.402

44.404

44.406

44.408

44.41

44.412

44.414

Longitude (o)

La

titu

de

(o)

OpenStreetMap osm file

(b) With an underlying image.

Figure 1.7: Examples of route plotting using plot_route and plot_way. Map data ©OpenStreetMap contributors, CC-BY-SA.