Reference

The MapData represents all data that have been processed from OpenStreetMap osm file This is the main data structure used fot map data analytics.

Fields

• bounds : bounds of the area map (stored as a Bounds object)
• nodes : dictionary of nodes representing all the objects on the map (with coordinates in East, North, Up system)
• roadways : unique roads stored as a set of Ways
• intersections : roads intersections
• g : Graphs directed graph representing a road network
• v : vertices in the road network (node id .=> graph vertex)
• n : vector of OpenStreetMap node ids for each corresponding graph vertex
• e : vector of edges in the graph represented as a tuple (source,destination)
• w : sparse matrix of edge weights, indexed by graph id
• class : road class of each edge

get_map_data(filepath::String,filename::Union{String,Nothing}=nothing;
             road_levels::Set{Int} = Set(1:length(OpenStreetMapX.ROAD_CLASSES)),
			 use_cache::Bool = true, only_intersections::Bool=true)::MapData

High level function - parses .osm file and create the road network based on the map data. This code currently can parse both *.osm and *.pbf (@blegat - thank you!) files. The data type is determined by file extension.

Arguments

• filepath : path with an .osm/.pbf file (directory or path to a file)
• filename : name of the file (when the first argument is a directory)
• road_levels : a set with the road categories (see: OpenStreetMapX.ROAD_CLASSES for more informations)
• use_cache : a *.cache file will be crated with a serialized map image in the datapath folder
• only_intersections : include only road system data
• trim_to_connected_graph: trim orphan nodes in such way that the map is a strongly connected graph

sample_map_path()

Produces a path to a sample map file.

sample_map()

Produces a MapData object in a lazy loaded way.

ECEF

Point in Earth-Centered-Earth-Fixed (ECEF) coordinates. Global cartesian coordinate system rotating with the Earth.

Constructors

ECEF(x::Float64, y::Float64, z::Float64)

LLA

Point in Latitude-Longitude-Altitude (LLA) coordinates Used to store node data in OpenStreetMapX XML files

Constructors

LLA(lat::Float64, lon::Float64)
LLA(lat::Float64, lon::Float64, alt::Float64)
LLA(xyz::XYZ)

Arguments

• lat : lattitude
• lon : Longitude
• alt : altitude

ENU

Point in East-North-Up (ENU) coordinates.

Local cartesian coordinate system. Linearized about a reference point.

Constructors

ENU(east::Float64, north::Float64, up::Float64)
ENU(east::Float64, north::Float64)
ENU(xyz::XYZ)

Bounds{T <: Union{LLA, ENU}}

Bounds for the LLA or ENUcoordinates. If T is not given Bounds{ENU} will be created.

center(bounds::Bounds{ENU})

Get Center Point of ENU Bounds Region

center(bounds::Bounds{LLA})

Get Center Point of LLA Bounds Region

inbounds(loc::ENU, bounds::Bounds{ENU})

Check Whether a location loc is within bounds bounds

inbounds(loc::LLA, bounds::Bounds{LLA})

Check whether a location loc is within bounds bounds

onbounds(loc::T, bounds::Bounds{T}) where T<:Union{LLA,ENU}

Check whether a location loc is onbounds bounds Works only for points that have passed the inbounds test

latlon(m::MapData,map_g_point_id::Int64)::Tuple{Float64, Float64}

Returns a tuple of lattitute and longitude for a given graph node identifier map_g_point_id in graph m.g (i.e. map_g_point_id ∈ 1:nv(m.g)).

getX(lla::OpenStreetMapX.LLA)

Point Translator gets longitude

getX(enu::OpenStreetMapX.ENU)

Point Translator gets enu east value

getY(lla::OpenStreetMapX.LLA)

Point Translator gets lattitude

getY(enu::OpenStreetMapX.ENU)

Point Translator gets enu north value

getZ(lla::OpenStreetMapX.LLA)

Point Translator gets altitude

getZ(enu::OpenStreetMapX.ENU)

Point Translator gets up value

World Geodetic Coordinate System of 1984 (WGS 84) Standardized coordinate system for Earth Global ellipsoidal reference surface

generate_point_in_bounds([rng::AbstractRNG], m::MapData)

Generates a random pair of Latitude-Longitude coordinates within boundaries of map m

point_to_nodes(point::Tuple{Float64,Float64}, m::MapData)

Converts a pair Latitude-Longitude of coordinates point to a node on a map m The result is a node indentifier.

point_to_nodes(point::LLA, m::MapData)

Converts a pair of coordinates LLA (Latitude-Longitude-Altitude) point to a node on a map m The result is a node indentifier.

shortest_route(m::MapData, node1::Int, node2::Int; routing::Symbol = :astar)

Find Shortest route between node1 and node2 on map m.

shortest_route(m::MapData, node1::Int, node2::Int, node3::Int; routing::Symbol = :astar)

Find Shortest route between node1 and node2 and node3 on map m.

fastest_route(m::MapData, node1::Int, node2::Int;
                    routing::Symbol = :astar,
                    speeds::Dict{Int,Float64}=SPEED_ROADS_URBAN)

Find fastest route between node1 and node2 on map m with assuming speeds for road classes.

fastest_route(m::MapData, node1::Int, node2::Int, node3::Int;
                    routing::Symbol = :astar,
                    speeds::Dict{Int,Float64}=SPEED_ROADS_URBAN)

Find fastest route between node1 and node2 and node3 on map m with assuming speeds for road classes.

a_star_algorithm(g::AbstractGraph{U},  
                s::Integer,                       
                t::Integer,                       
                distmx::AbstractMatrix{T}=Graphs.weights(g),
                heuristic::Function = (u,v) -> zero(T)) where {T, U}

High level function - implementation of A star search algorithm: (https://en.wikipedia.org/wiki/A*searchalgorithm). Based on the implementation in Graphs library, however significantly improved in terms of performance.

Arguments

• g : graph object
• S : start vertex
• t : end vertex
• distmx : distance matrix
• heuristic : search heuristic function; by default returns zero

a_star_algorithm(m::MapData,  
                s::Integer,                       
                t::Integer)

A star search algorithm with straight line distance heuristic

Arguments

• m : MapData object
• S : start vertex
• t : end vertex
• distmx : distance matrix

distance(a::ENU, b::ENU)

Calculates a distance between two points a and b

distance(a::ECEF, b::ECEF)

Calculates a distance between two points a and b

distance(x1, y1, z1, x2, y2, z2)

Calculates eclidean distance in three dimensions.

distance(nodes::Dict{Int,T}, route::AbstractVector{Int}) where T<:(Union{OpenStreetMapX.ENU,OpenStreetMapX.ECEF})

Compute the distance of a route for some nodes data

Get Distances Between Edges

get_distance(A::Int, B::Int, 
             nodes::Dict{Int,T} , 
             vertices_to_nodes::Vector{Int}) where T<:Union{OpenStreetMapX.ENU,OpenStreetMapX.ECEF}

Auxiliary function - takes two vertices of graph and return the distance between them. Used to compute straight line distance heuristic for A* algorithm.

Arguments

• A : start vertex
• B : end vertex
• nodes : dictionary of .osm nodes ID's and correspoding points coordinates
• vertices_to_nodes : dictionary mapping graph vertices to .osm file nodes

nodes_within_driving_time(m::MapData, start_indices::Vector{Int}, limit::Float64=Inf, speeds::Dict{Int,Float64}=SPEED_ROADS_URBAN)

nodes_within_driving_time(nodes::Dict{Int,T}, m::MapData, loc::T, limit::Float64=Inf, locrange::Float64=500.0, speeds::Dict{Int,Float64}=SPEED_ROADS_URBAN) where T<:(Union{OpenStreetMapX.ENU,OpenStreetMapX.ECEF})

Extract Nodes from bellman_fordStates Object Within an (Optional) Limit ### Based on Driving Time ###

nodes_within_driving_distance(m::MapData, start_indices::Vector{Int}, limit::Float64=Inf)

Extract Nodes from bellman_fordStates Object Within an (Optional) Limit ### Based on Driving Distance ###

nodes_within_weights(m::MapData, weights::SparseArrays.SparseMatrixCSC{Float64,Int64}, start_indices::Vector{Int}, limit::Float64=Inf)

Extract Nodes from bellman_fordStates Object Within an (Optional) Limit ### Based on Weights ###

nearest_node(nodes::Dict{Int,T}, loc::T) where T<:(Union{OpenStreetMapX.ENU,OpenStreetMapX.ECEF})

Find the nearest node to a given location loc

nearest_node(m::MapData, loc::ENU, vs_only::Bool=true)

Find the nearest node to a given location loc

nearest_node(nodes::Dict{Int,T}, loc::T, node_list::AbstractSet{Int}) where T<:(Union{OpenStreetMapX.ENU,OpenStreetMapX.ECEF})

Find the nearest node in a list of nodes

nodes_within_range(nodes::Dict{Int,T}, loc::T, range::Float64 = Inf) where T<:(Union{OpenStreetMapX.ENU,OpenStreetMapX.ECEF})

Find all nodes within range of a location

nodes_within_range(nodes::Dict{Int,T}, loc::T, node_list::AbstractSet{Int}, range::Float64 = Inf) where T<:(Union{OpenStreetMapX.ENU,OpenStreetMapX.ECEF})

Find nodes within range of a location using a subset of nodes

nodes_within_range(nodes::Dict{Int,T},loc::T, m::OpenStreetMapX.MapData, range::Float64 = Inf) where T <:(Union{OpenStreetMapX.ENU,OpenStreetMapX.ECEF})

Find vertices of a routing network within range of a location

get_google_route(origin::Int, destination::Int,
                 map_data:MapData, googleapi_key::String;
                 googleapi_parameters::Dict{Symbol,String} = googleAPI_parameters)

Get route from to based on Google Distances API with two points (origin and destination) on map map_data using Google API key googleapi_key with optional Google Distances API request parameters googleapi_parameters.

get_google_route(origin::Int, destination::Int, waypoint::Int,
                 map_data:MapData, googleapi_key::String;
                 googleapi_parameters::Dict{Symbol,String} = googleAPI_parameters)

Get route from to based on Google Distances API with three points (origin, destination and waypoint between) on map map_data using Google API key googleapi_key with optional Google Distances API request parameters googleapi_parameters.

node_to_string(node_id::Int,map_data::MapData)

Convert node coordinates (stored in ENU system in the nodes field of map_data) identified by node_id to string with LLA system coordinates

Dictionary for Google Distances API requests:

Keys

• :url : url for google API, only JSON files outputs are accepted
• :mode : transportation mode used in simulation, in the current library scope only driving is accepted
• :avoid : map features to avoid (to mantain compatibility with OSM routes ferries should be avoided)
• :units : unit system for displaing distances (changing to imperial needs deeper changes in both OSMsim and OpenStreetMapX modules)

Encode single coordinate (multiplied by 1e5 and rounded) in Google Polyline Algorithm Format

Arguments

• val : single coordinate (multiplied by 1e5 and rounded)

Encode coordinates in Google Polyline Algorithm Format

Arguments

• coords : coordinates in LLA system stored as a tuple

Decode single coordinate

Arguments

• polyline : coordinates in Google Polyline Algorithm Format stored as an array of characters
• index : position of each single coordinate in polyline array

Decode coordinates in Google Polyline Algorithm Format

Arguments

• polyline : string containing coordinates in Polyline Algorithm Format

ROAD_CLASSES

Road classes. Information used for routing and plotting.

Ordered by typical significance

CYCLE_CLASSES

Cycle classes - Level 1: Bike paths - Level 2: Separated bike lanes (tracks) - Level 3: Bike lanes - Level 4: Bikes typically allowed but not specified

PED_CLASSES

Pedestrain paths

- Level 1: Cycleways, walking paths, and pedestrian streets
- Level 2: Sidewalks
- Level 3: Pedestrians typically allowed but unspecified
- Level 4: Agricultural or horse paths, etc.

Default Speed Limits in Kilometers Per Hour in urban areas

Default Speed Limits in Kilometers Per Hour in rural areas

Ways in OSM data

Relations in OSM data

boundary_point(p1::T, p2::T, bounds::Bounds{T}) where T<:Union{LLA,ENU}

Find the closest point within bounds Works only for points where inbounds(p1) != inbounds(p2)

centroid(nodes::Dict{Int,T}, node_list::Vector{Int}) where T<:(Union{OpenStreetMapX.LLA,OpenStreetMapX.ENU})

Compute Centroid of List of Nodes

classify_cycleways(ways::Vector{OpenStreetMapX.Way},
                   classes::Dict{String, Int} = OpenStreetMapX.CYCLE_CLASSES)

Classifies a vector of OpenStreetMapX ways based on their cycleway attributes. It considers the presence of "bicycle", "cycleway", and "highway" tags and checks if the corresponding values or the constructed class strings are present in the specified classes dictionary.

Arguments

• ways::Vector{OpenStreetMapX.Way} : Way's vector
• classes : classes dictionary

classify_walkways(ways::Vector{OpenStreetMapX.Way},
                  classes::Dict{String, Int} = OpenStreetMapX.PED_CLASSES)

Classifies a vector of OpenStreetMapX ways based on their pedestrian attributes. It considers the presence of a "sidewalk" tagand checks if the corresponding value or the "highway" tag value is present in the specified classes dictionary

Arguments

• ways::Vector{OpenStreetMapX.Way} : Way's vector
• classes : classes dictionary

crop!(nodes::Dict, bounds::OpenStreetMapX.Bounds, way::OpenStreetMapX.Way)

Crop Single Way

crop!(nodes::Dict, bounds::OpenStreetMapX.Bounds, ways::Vector{OpenStreetMapX.Way})

Crop Ways

crop!(nodes::Dict, bounds::OpenStreetMapX.Bounds, ways::Vector{OpenStreetMapX.Way},relations::Vector{OpenStreetMapX.Relation}, relation::OpenStreetMapX.Relation)

Crop Single Relation

crop!(nodes::Dict, bounds::OpenStreetMapX.Bounds, ways::Vector{OpenStreetMapX.Way}, relations::Vector{OpenStreetMapX.Relation})

Crop Relations

crop!(nodes::Dict, bounds::OpenStreetMapX.Bounds, features::Dict, id::Int)

Crop Single Node and Feature

crop!(nodes::Dict, bounds::OpenStreetMapX.Bounds, features::Dict)

Crop Nodes and Features

crop!(map::OpenStreetMapX.OSMData; crop_relations = true, crop_ways = true, crop_nodes = true)

Crop Map

"" extract_highways(ways::Vector{OpenStreetMapX.Way})

Extract Highways

For Each Feature Find the Nearest Graph Node ###

filter_cycleways(ways::Vector{OpenStreetMapX.Way},
                classes::Dict{String, Int} = OpenStreetMapX.CYCLE_CLASSES;
                levels::Set{Int} = Set(1:length(OpenStreetMapX.CYCLE_CLASSES)))

Filters a vector of OpenStreetMapX ways to include only those that are relevant for cycleways. It considers the presence of "bicycle", "cycleway", and "highway" tags and checks if the corresponding values or the constructed class strings are present in the specified classes dictionary and levels set.

Arguments

• ways::Vector{OpenStreetMapX.Way} : Way's vector
• classes : classes dictionary
• levels : set of levels useful to compare with the way tags

filter_highways(ways::Vector{OpenStreetMapX.Way})

filter_walkways(ways::Vector{OpenStreetMapX.Way},
                classes::Dict{String, Int} = OpenStreetMapX.PED_CLASSES;
                levels::Set{Int} = Set(1:length(OpenStreetMapX.PED_CLASSES)))

Filters a vector of ways to include only those that are relevant for pedestrian walkways. It considers the presence of a "sidewalk" tag and checks if the corresponding value or the "highway" tag value is present in the specified classes dictionary and levels set.

Arguments

• ways::Vector{OpenStreetMapX.Way} : Way's vector
• classes : classes dictionary
• levels : set of levels useful to compare with the way tags

find_intersections(highways::Vector{OpenStreetMapX.Way})

Find Intersections of Highways

find_optimal_waypoint_approx(m::MapData, weights::SparseArrays.SparseMatrixCSC{Float64,Int64}, node0::Int, node1::Int, waypoints::Dict{Int,Int})

Find waypoint minimizing the route. Returns an approximate solution.

find_optimal_waypoint_exact(m::MapData, weights::SparseArrays.SparseMatrixCSC{Float64,Int64}, node0::Int, node1::Int, waypoints::Dict{Int,Int})

Find waypoint minimizing the route. Returns an exact solution.

find_route(m::MapData, node0::Int, node1::Int, node2::Int,
                    weights::SparseArrays.SparseMatrixCSC{Float64,Int64};
                    routing::Symbol = :astar, heuristic::Function = (u,v) -> zero(Float64),
                    get_distance::Bool = false, get_time::Bool = false)

Find Route Connecting 3 Points (node0, node1, node2) with Given Weights

find_segments(nodes::Dict{Int,T}, highways::Vector{OpenStreetMapX.Way}, intersections::Dict{Int,Set{Int}}) where T<:Union{OpenStreetMapX.ENU,OpenStreetMapX.ECEF}

Find Segments of Highways