Welcome to OpenStreetMap.jl’s documentation!¶

Features¶

The following features are provided:

• Parse an OpenStreetMap XML datafile (OSM files)

• Crop maps to specified boundaries

• Convert maps between LLA, ECEF, and ENU coordinates

• Extract highways, buildings, and tagged features from OSM data

• Filter data by various classes

  • Ways suitable for driving, walking, or cycling
  • Freeways, major city streets, residential streets, etc.
  • Accomodations, shops, industry, etc.

• Draw detailed maps using Julia’s Winston graphics package with a variety of options

• Compute shortest or fastest driving, cycling, and walking routes using Julia’s Graphs package

Package Status¶

All the functionality that I personally need for my work is now implemented in this package. Therefore, future updates will depend on GitHub issues (bug reports or feature requests) created by users. Pull requests for additional functionality are very welcome, as well.

Map Data¶

These types pertain directly to map elements.

type Highway
    class::String       # Type of highway
    lanes::Int          # Number of lanes (1 if unspecified)
    oneway::Bool        # True if road is one-way
    sidewalk::String    # Sidewalk classifier, if available
    cycleway::String    # Cycleway classifier, if available
    bicycle::String     # Bicycle classifier, if available
    name::String        # Name, if available
    nodes::Vector{Int}  # List of nodes
end

type Segment
    node0::Int          # Source node ID
    node1::Int          # Target node ID
    nodes::Vector{Int}  # List of nodes falling within node0 and node1
    class::Int          # Class of the segment
    parent::Int         # ID of parent highway
    oneway::Bool        # True if road is one-way
end

type Feature
    class::String       # Shop, amenity, crossing, etc.
    detail::String      # Class qualifier
    name::String        # Name
end

type Building
    class::String       # Building type (usually "yes")
    name::String        # Building name (usually unavailable)
    nodes::Vector{Int}  # List of nodes
end

type Intersection
    highways::Set{Int} # Set of highway IDs
end

type Bounds
    min_y::Float64    # min_lat or min_north
    max_y::Float64    # max_lat or max_north
    min_x::Float64    # min_lon or min_east
    max_x::Float64    # max_lon or max_east
end

Point Types¶

These types give alternative representations for point locations in OpenStreetMap.jl.

type LLA
    lat::Float64
    lon::Float64
    alt::Float64
end

type ECEF
    x::Float64
    y::Float64
    z::Float64
end

type ENU
    east::Float64
    north::Float64
    up::Float64
end

Additional Types¶

type Network
    g        # Incidence graph of streets
    v        # Dictionary of vertices indexed by their OSM node IDs
    w        # Edge weights
    class    # Edge classification
end

type Style
    color::Uint32   # Line color
    width::Real     # Line width
    spec::String    # Line type
end

style(x, y) = style(x, y, "-")

Extracting Intersections¶

A simple function is provided to find all highway ends and intersections:

findIntersections(highways::Dict{Int, Highway})¶

The only required input is the highway dictionary returned by “getOSMData().” A dictionary of “Intersection” types is returned, intexed by the node ID of the intersection.

In some cases, such as boulevards and other divided roads, OpenStreetMap represents a street as two one-way highways. This can result in multiple “intersections” detected per true intersection. If desired, these intersections can be “clustered,” replacing these multiple intersection-lets with a single node. This gives a better estimate of the total number of highway intersections in a region.

To do this, we first “cluster” the highways, by gathering all highways with a common name (note that this is dependent on the quality of street name tags in your source data). We then search for proximal instances of these highway sets crossing one another. Flag max_dist can be used to change the required proximity of the nodes to be considered an intersection (the default is 15 meters). Note that this proximity is the maximum distance the node can be from the centroid of all nodes in the intersection at the time the node is added. If an intersection involves the same highways as an existing cluster during the search but is further away than max_dist, a new cluster will be formed, initialized at that point.

The code to accomplish this is as follows:

highway_sets = findHighwaySets(highways)
intersection_mapping = findIntersectionClusters(nodes,intersections,highway_sets,max_dist=15)
replaceHighwayNodes!(highways,intersection_mapping)
cluster_node_ids = unique(collect(values(intersection_mapping)))

The optional flag “max_dist” is in the units of your “nodes” object.

Working with Segments¶

Usually routing can be simplified to the problem of starting and ending at a specified intersection, rather than any node in a highway. In these cases, we can use “Segments” rather than “Highways” to greatly reduce the computation required to compute routes. Segments are subsets of highways that begin and end on nodes, keep track of their parent highway, and hold all intermediate nodes in storage (allowing them to be converted back to Highway types for plotting or cropping). The following functions extract Segments from Highways and convert Segments to Highways, respectively:

segmentHighways(highways, intersections, classes, levels=Set(1:10))¶

highwaySegments(segments::Vector{Segment})¶

Note: By default, segmentHighways() converts only the first 10 levels into segments. If you wish to exclude certain road classes, you should do so here prior to routing. By default, OpenStreetMap.jl uses only 8 road classes, but only classes 1-6 represent roads used for typical routing (levels 7 and 8 are service and pedestrian roads, such as parking lot entrances and driveways). In the United States, roads with class 8 should not be used by cars.

OpenStreetMap Interface¶

On OpenStreetMap.org, there is a big “Export” button at the top. For very small regions, this is the best option, because the region boundary will be embedded in the file for you (so you don’t have to record it). Just drag the box around your region and click export. Easy!

If your region is too large, you will usually just get a blank page in your browser without any error messages. If this happens, there is a link below the “Export” button that says “Overpass API.” This will very conveniently send your region to the API for an automatic download through that system. Unforunately, this .osm file will not include the boundary information, so you will not be able to use OpenStreetMap.jl’s convenient getBounds function. Otherwise, as far as I can tell, it’s the same as clicking the “Export” button.

Overpass API Interface¶

If you’re not the type to like easy interfaces like dragging a box around your desired region and clicking a button, then this is the option for you! There are two ways to interact with the API. The syntax is confusing, so we will just download a simple rectangular region and do everything else happily within Julia.

The easist way to access the API is just directly through the web. The syntax is as follows:

http://overpass-api.de/api/map?bbox=minLon,minLat,maxLon,maxLat

Be sure to replace minLon, etc., with the decimal latitude and longitudes of your bounding box. This will download the file for you, but it is missing the ”.osm” extension (you can add this yourself, if you’d like). You can use this to script downloads, but please don’t overload the OpenStreetMap servers, which are donation-supported.

Cropping Maps¶

OSM XML files do not provide sharp edges on boundaries. Also, it is often the case that one wants to focus on one subregion of a large OSM file. A cropping function is provided for these cases:

function cropMap!(nodes::Dict,
                  bounds::Bounds;
                  highways=nothing,
                  buildings=nothing,
                  features=nothing,
                  delete_nodes::Bool=true)

Classifying Map Elements¶

OpenStreetMap.jl can classify map elements according to the following schemes: * Roadways [8 levels] * Cycleways [4 levels] * Walkways [4 levels] * Building Types [5 levels] * Feature Types [7 levels]

Each of these schemes classifies map elements using their OSM tags according to multiple levels. The definitions of these levels is encoded in classes.jl.

The following functions take their respective map element lists as the single parameter and output a classification dictionary of type Dict{Int,Int}. The keys of the dictionary are the highway ID numbers, and the values provide the classification of that map element.

• roadways(highways)
• walkways(highways)
• cycleways(highways)
• classify(buildings)
• classify(features)

These classification dictionaries can be used for both route planning and map plotting.

Converting Map Coordinate Systems¶

OpenStreetMap.jl is capable of converting map data between LLA, ECEF, and ENU coordinates (see “Data Types”) for definitions of these standard coordinates. Because point location data is ONLY stored in the nodes dictionary (type Dict{Int,Point-Type}), only this object needs to be converted. Note that Bounds objects also need to be converted, although they don’t technically store map data. The following functions can be used to convert between coordinate systems:

• ECEF(nodes::Dict{Int,LLA})
• LLA(nodes::Dict{Int,ECEF})
• ENU(nodes::Dict{Int,ECEF}, reference::LLA)
• ENU(nodes::Dict{Int,LLA}, reference::LLA)

East-North-Up coordinates require an additional input parameter, reference, which gives the origin of the ENU coordinate system. LLA and ECEF coordinates both have their origins fixed at the center of the earth.

Transportation Network¶

In order to plot routes within the map, the streets must first be converted into a transportation network using createGraph():

createGraph(nodes, highways, classes, levels)¶

Inputs:

• nodes [Dict{Int,ENU} or Dict{Int,ECEF}]: Dictionary of node locations
• highways [Dict{Int,Highway}]: Dictionary of highways
• classes [Dict{Int,Int}]: Dictionary of highway classifications
• levels [Set{Integer}]: Set of highway classification levels allowed for route planning

Output:

• Network type, containing all data necessary for route planning with Graphs.jl

A transportation network graph can alternatively be created using highway “segments” rather than highways. These segments begin and end at intersections, eliminating all intermediate nodes, and can greatly speed up route planning.

createGraph(segments, intersections)

Inputs:

• segments [Vector{Segment}]: Vector of segments
• intersections [Dict{Int,Intersection}]: Dictionary of intersections, indexed by node ID

Output:

• Network type, containing all data necessary for route planning with Graphs.jl

Route Planning¶

Driving Regions¶

In addition to providing individual routes, the following functions can also be used for retrieving the set of nodes that are within a driving distance limit from a given starting point.

Data Inputs¶

These parameters provided the actual data to be plotted.

• nodes [Dict{Int,LLA} or Dict{Int,ENU}]: List of all point locations
• features [Dict{Int,Feature}]: List of features to display
• buildings [Dict{Int,Building}]: List of buildings to display
• highways [Dict{Int,Highway}]: List of highways to display
• intersections [Dict{Int,Intersection}]: List of highway intersections
• route [Vector{Int} or Vector{Vector{Int}}]: List of nodes comprising a highway route OR a list of lists of routes (if multiple routes are to be displayed).

Data Classifiers¶

These parameters classify the map elements according to a layer specification. When these parameters are passed to plotMap(), only the classified map elements are plotted (all map elements not in these dictionaries are ignored).

• roadways: Dictionary of highway types suitable for driving
• cycleways: Dictionary of highway types suitable for cycling
• walkways: Dictionary of highway types suitable for walking
• building_classes: Dictionary of building classifications
• feature_classes: Dictionary of feature classifications

Note 1: These layers use their own Layer dictionaries, containing one Style type for each element classification level, to define plotting styles. Therefore, any additional style inputs related to these classifiers will be ignored without any explicit warnings to the user.

Note 2: Using multiple highway classifiers on one plot may cause them to overlap and occlude one another. The ordering, from bottom to top, is roadways, cycleways, walkways.

Plot Display Options¶

• bounds [Bounds]: X and Y axes limits of plot, also used to compute appropriate plot aspect ratio
• width [Integer]: Width of the plot, in pixels
• fontsize [Integer]: Fontsize of axes labels. If 0, let Winston decide (default). Use this if you need consistency amongst many plots.
• km [Bool]: If nodes is in ENU coordinates, converts plot axes to use kilometers rather than meters
• realtime [Bool]: When true, elements are added to the map individually (this drastically slows down plotting, but is fun to watch)

Plot Customization¶

The following optional inputs allow the user to customize the map display.

• highway_style [Style or Dict{Int,Style}]: See note 3 below.
• building_style [Style or Dict{Int,Style}]: See note 3 below.
• feature_style [Style or Dict{Int,Style}]: See note 3 below.
• route_style [Style or Vector{Style}]: Use an vector of Style types to plot multiple routes with different appearances.
• intersection_style [Style]

These inputs all take a Style type, which is constructed as follows:

style = OpenStreetMap.Style(color, width, spec)

For example:

highway_style = OpenStreetMap.Style("b", 1.5, "-")
feature_style = OpenStreetMap.Style(0xf57900, 2, ".")

Note 1: color must be a hex color code.

Note 2: spec is a line specification code used by Winston.jl. Common examples are the following:

• "-": Solid line
• ".": Filled, square points
• "o": Open, round points

Note 3: For highways, buildings, and features, if an additional classifier is input (e.g., roadways), the respective style input must be a dictionary of styles, with type Dict{Int,Style}, with a style given for each classification. This dictionary is called a “layer” in OpenStreetMap terminology, and defines how a specific map layer is displayed. The default layers are defined as constants in layers.jl.

Saving Map Images¶

plotMap() returns the Winston.FramedPlot object. This allows the user to futher modify the plot or save it using the file function available from Winston.jl with the desired aspect ratio.

Example of saving a plot as an image in png, eps, and pdf formats:

p = plotMap(nodes, bounds=bounds, highways=highways)
width = 500
aspect_ratio = OpenStreetMap.aspectRatio(bounds)
height = int(width / aspect_ratio)
Winston.file(p, "filename.png", "width", width, "height", height)
Winston.file(p, "filename.eps", "width", width, "height", height)
Winston.file(p, "filename.pdf", "width", width, "height", height)