Merge pull request #71 from tedsteiner/test-examples

Fixed examples in documentation (Issue #69).

.gitignore

@@ -6,3 +6,4 @@ _templates
 *.swp
 *~
 test/tech_square.osm
+test/osm_map.png

docs/examples.rst

@@ -1,24 +1,42 @@
 Examples
 ========
 
+The following example walks through a sample workflow using OpenStreetMap.jl. This page does not cover all functionality available in OpenStreetMap.jl, but hopefully helps new users get started quickly. See also "test/examples.jl" for all of these examples together in a single Julia file.
+
 Read data from an OSM XML file:
 
 .. code-block:: python
 
-    nodes, hwys, builds, feats = getOSMData(MAP_FILENAME)
+    nodesLLA, highways, buildings, features = getOSMData(MAP_FILENAME)
+
+    println("Number of nodes: $(length(nodesLLA))")
+    println("Number of highways: $(length(highways))")
+    println("Number of buildings: $(length(buildings))")
+    println("Number of features: $(length(features))")
+
+
+Define map boundary:
+
+.. code-block:: python
+
+    boundsLLA = Bounds(42.365, 42.3675, -71.1, -71.094)
+
+
+Define reference point and convert to ENU coordinates:
+
+.. code-block:: python
+
+    lla_reference = center(boundsLLA)
+    nodes = ENU(nodesLLA, lla_reference)
+    bounds = ENU(boundsLLA, lla_reference)
 
-    println("Number of nodes: $(length(nodes))")
-    println("Number of highways: $(length(hwys))")
-    println("Number of buildings: $(length(builds))")
-    println("Number of features: $(length(feats))")
 
-Define map boundary and crop:
+Crop map to boundary:
 
 .. code-block:: python
 
-    bounds = Bounds(42.365, 42.3675, -71.1, -71.094)
+    cropMap!(nodes, bounds, highways=highways, buildings=buildings, features=features, delete_nodes=false)
 
-    cropMap!(nodes, bounds, highways=hwys, buildings=builds, features=feats, delete_nodes=false)
 
 Find highway intersections:
 
@@ -28,6 +46,7 @@ Find highway intersections:
 
     println("Found $(length(inters)) intersections.")
 
+
 Extract map components and classes:
 
 .. code-block:: python
@@ -38,78 +57,109 @@ Extract map components and classes:
     bldg_classes = classify(builds)
     feat_classes = classify(feats)
 
-Convert map nodes to ENU coordinates:
+
+Convert map nodes to East-North-Up (ENU) coordinates:
 
 .. code-block:: python
 
     reference = center(bounds)
     nodesENU = ENU(nodes, reference)
     boundsENU = ENU(bounds, reference)
 
-Create transportation network:
+
+Extract highway classes (note that OpenStreetMap calls paths of any form "highways"):
+
+.. code-block:: python
+
+    roads = roadways(highways)
+    peds = walkways(highways)
+    cycles = cycleways(highways)
+    bldg_classes = classify(buildings)
+    feat_classes = classify(features)
+    
+
+Find all highway intersections:
+
+.. code-block:: python
+
+    intersections = findIntersections(highways)
+    
+    
+Segment only specific levels of roadways (e.g., freeways (class 1) through residential streets (class 6)):
+
+.. code-block:: python
+
+    segments = segmentHighways(nodes, highways, intersections, roads, Set(1:6))
+
+
+Create transportation network from highway segments:
 
 .. code-block:: python
 
-    network = createGraph(nodesENU, hwys, roads, Set(1:8))
+    network = createGraph(segments, intersections)
 
-    println("Graph formed with $(Graphs.num_vertices(network.g)) vertices and $(Graphs.num_edges(network.g)) edges.")
 
-Route planning:
+Compute the shortest and fastest routes from point A to B:
 
 .. code-block:: python
 
     loc_start = ENU(-5000, 5500, 0)
     loc_end = ENU(5500, -4000, 0)
 
-    node0 = nearestNode(nodesENU, loc_start, network.v_inv)
-    node1 = nearestNode(nodesENU, loc_end, network.v_inv)
+    node0 = nearestNode(nodes, loc_start, network)
+    node1 = nearestNode(nodes, loc_end, network)
     shortest_route, shortest_distance = shortestRoute(network, node0, node1)
 
     fastest_route, fastest_time = fastestRoute(network, node0, node1)
-    fastest_distance = distance(nodesENU, fastest_route)
+    fastest_distance = distance(nodes, fastest_route)
 
     println("Shortest route: $(shortest_distance) m  (Nodes: $(length(shortest_route)))")
     println("Fastest route: $(fastest_distance) m  Time: $(fastest_time/60) min  (Nodes: $(length(fastest_route)))")
 
-Display shortest and fastest routes:
+
+Display the shortest and fastest routes:
 
 .. code-block:: python
 
     fignum_shortest = plotMap(nodesENU, highways=hwys, bounds=boundsENU, roadways=roads, route=shortest_route)
 
     fignum_fastest = plotMap(nodesENU, highways=hwys, bounds=boundsENU, roadways=roads, route=fastest_route)
 
-Extract nearby Nodes (within range)
+
+Extract Nodes near to (within range) our route's starting location:
 
 .. code-block:: python
 
-    loc0 = nodesENU[node0]
-    filteredENU = filter((k,v)->haskey(network.v,k), nodesENU)
+    loc0 = nodes[node0]
+    filteredENU = filter((k,v)->haskey(network.v,k), nodes)
     local_indices = nodesWithinRange(filteredENU, loc0, 100.0)
 
-Identify Driving Catchment Areas (within limit)
+
+Identify Driving Catchment Areas (within limit):
 
 .. code-block:: python
 
     start_index = nearestNode(filteredENU, loc0)
     node_indices, distances = nodesWithinDrivingDistance(network, local_indices, 300.0)
 
-Alternatively, switch to catchment areas based on driving time, rather than distance
+
+Alternatively, switch to catchment areas based on driving time, rather than distance:
 
 .. code-block:: python
 
     node_indices, distances = nodesWithinDrivingTime(network, local_indices, 50.0)
 
+
 Display classified roadways, buildings, and features:
 
 .. code-block:: python
 
-    fignum = plotMap(nodesENU,
-                     highways=hwys,
-                     buildings=builds,
-                     features=feats,
-                     bounds=boundsENU,
-                     width=1000,
+    fignum = plotMap(nodes,
+                     highways=highways,
+                     buildings=buildings,
+                     features=features,
+                     bounds=bounds,
+                     width=500,
                      feature_classes=feat_classes,
                      building_classes=bldg_classes,
                      roadways=roads)

src/nodes.jl

@@ -2,6 +2,7 @@
 ### MIT License                 ###
 ### Copyright 2014              ###
 
+
 ### Find the nearest node to a given location ###
 function nearestNode{T<:Union(ENU,ECEF)}(nodes::Dict{Int,T}, loc::T)
     min_dist = Inf
@@ -18,6 +19,8 @@ function nearestNode{T<:Union(ENU,ECEF)}(nodes::Dict{Int,T}, loc::T)
     return best_ind
 end
 
+
+### Find nearest node in a list of nodes ###
 function nearestNode{T<:Union(ENU,ECEF)}(nodes::Dict{Int,T},
                                          loc::T,
                                          node_list::Vector{Int})
@@ -35,6 +38,16 @@ function nearestNode{T<:Union(ENU,ECEF)}(nodes::Dict{Int,T},
     return best_ind
 end
 
+
+### Find nearest node serving as a vertex in a routing network ###
+function nearestNode{T<:Union(ENU,ECEF)}( nodes::Dict{Int,T},
+                                          loc::T,
+                                          network::Network )
+    return nearestNode(nodes,loc,collect(keys(network.v)))
+end
+
+
+### Find all nodes within range of a location ###
 function nodesWithinRange{T<:Union(ENU,ECEF)}(nodes::Dict{Int,T},
                                              loc::T,
                                              range::Float64=Inf)
@@ -50,7 +63,9 @@ function nodesWithinRange{T<:Union(ENU,ECEF)}(nodes::Dict{Int,T},
     end
     return indices
 end
+
 
+### Find nodes within range of a location using a subset of nodes ###
 function nodesWithinRange{T<:Union(ENU,ECEF)}(nodes::Dict{Int,T},
                                               loc::T,
                                               node_list::Vector{Int},
@@ -68,6 +83,16 @@ function nodesWithinRange{T<:Union(ENU,ECEF)}(nodes::Dict{Int,T},
     return indices
 end
 
+
+### Find vertices of a routing network within range of a location ###
+function nodesWithinRange{T<:Union(ENU,ECEF)}(nodes::Dict{Int,T},
+                                              loc::T,
+                                              network::Network,
+                                              range::Float64=Inf)
+    return nodesWithinRange(nodes,loc,collect(keys(network.v)),range)
+end
+
+
 ### Add a new node ###
 function addNewNode!{T<:Union(LLA,ENU)}(nodes::Dict{Int,T}, 
                                         loc::T, 
@@ -85,6 +110,7 @@ function addNewNode!{T<:Union(LLA,ENU)}(nodes::Dict{Int,T},
     throw(OverflowError(msg))
 end
 
+
 ### Compute centroid of list of nodes ###
 function centroid{T<:Union(LLA,ENU)}(nodes::Dict{Int,T}, node_list::Vector{Int})
     sum_1 = 0

test/examples.jl

@@ -0,0 +1,99 @@
+# Test that example workflow from documentation works
+
+module TestExamples
+
+using OpenStreetMap
+import Winston
+
+const MAP_FILENAME = "tech_square.osm"
+
+# Read data from an OSM XML file
+nodesLLA, highways, buildings, features = getOSMData( MAP_FILENAME )
+println("Number of nodes: $(length(nodesLLA))")
+println("Number of highways: $(length(highways))")
+println("Number of buildings: $(length(buildings))")
+println("Number of features: $(length(features))")
+
+
+# Get bounds from OSM file
+# (This is not always available, depending on how OSM data was exported.)
+boundsLLA = getBounds(parseMapXML(MAP_FILENAME))
+
+
+# Convert to ENU coordinates
+lla_reference = center(boundsLLA) # Manual reference point for coordinate transform (optional)
+nodes = ENU( nodesLLA, lla_reference )
+bounds = ENU( boundsLLA, lla_reference )
+
+
+# Crop map to bounds
+cropMap!(nodes, bounds, highways=highways, buildings=buildings, features=features, delete_nodes=false)
+
+
+# Extract highway classes (note that OpenStreetMap calls all paths “highways”
+roads = roadways(highways)
+peds = walkways(highways)
+cycles = cycleways(highways)
+bldg_classes = classify(buildings)
+feat_classes = classify(features)
+
+
+# Find all highway intersections
+intersections = findIntersections(highways)
+
+
+# Segment only specific levels of roadways
+# (e.g., freeways through residential streets, levels 1-6)
+segments = segmentHighways(nodes, highways, intersections, roads, Set(1:6))
+
+
+# Create the routing network
+network = createGraph(segments, intersections)
+
+
+# Compute the shortest and fastest routes from point A to B
+loc_start = ENU(-5000, 5500, 0)
+loc_end = ENU(5500, -4000, 0)
+
+node0 = nearestNode(nodes, loc_start, network)
+node1 = nearestNode(nodes, loc_end, network)
+shortest_route, shortest_distance = shortestRoute(network, node0, node1)
+
+fastest_route, fastest_time = fastestRoute(network, node0, node1)
+fastest_distance = distance(nodes, fastest_route)
+
+println("Shortest route: $(shortest_distance) m  (Nodes: $(length(shortest_route)))")
+println("Fastest route: $(fastest_distance) m  Time: $(fastest_time/60) min  (Nodes: $(length(fastest_route)))")
+
+
+# Display the shortest and fastest routes
+fignum_shortest = plotMap(nodes, highways=highways, bounds=bounds, roadways=roads, route=shortest_route)
+
+fignum_fastest = plotMap(nodes, highways=highways, bounds=bounds, roadways=roads, route=fastest_route)
+
+
+# Extract Nodes near to (within range) our route's starting location:
+loc0 = nodes[node0]
+filteredENU = filter((k,v)->haskey(network.v,k), nodes)
+local_indices = nodesWithinRange(filteredENU, loc0, 100.0)
+
+
+# Identify Driving Catchment Areas (within limit):
+start_index = nearestNode(filteredENU, loc0)
+node_indices, distances = nodesWithinDrivingDistance(network, local_indices, 300.0)
+
+node_indices, distances = nodesWithinDrivingTime(network, local_indices, 50.0)
+
+fignum = plotMap(nodes,
+                 highways=highways,
+                 buildings=buildings,
+                 features=features,
+                 bounds=bounds,
+                 width=500,
+                 feature_classes=feat_classes,
+                 building_classes=bldg_classes,
+                 roadways=roads)
+
+Winston.savefig("osm_map.png")
+
+end # module TestExamples

test/routes.jl

@@ -82,8 +82,8 @@ intersections = findIntersections(hwys)
 segments = segmentHighways(nodesENU, hwys, intersections, roads, Set(1:8))
 segment_network = createGraph(segments, intersections)
 
-node0 = nearestNode(nodesENU, loc_start, collect(keys(segment_network.v)))
-node1 = nearestNode(nodesENU, loc_end, collect(keys(segment_network.v)))
+node0 = nearestNode(nodesENU, loc_start, segment_network)
+node1 = nearestNode(nodesENU, loc_end, segment_network)
 
 # Shortest route
 _, shortest_segment_distance = shortestRoute(segment_network, node0, node1)

test/runtests.jl

@@ -1,3 +1,5 @@
+module OSMTests
+
 using OpenStreetMap
 using Base.Test
 
@@ -8,9 +10,12 @@ tests = [
     "classes",
     "intersections",
     "routes",
-    "plots" ]
+    "plots",
+    "examples" ]
 
 for t in tests
     println("testing $t ...")
     @time include("$t.jl")
 end
+
+end # Module OSMTests