Rename OSM.intersection and OSM.road (#594)

* Rename `OSM.intersection` and `OSM.road`

* Fix line spacing change

* Fix `nearest_node` conflict

docs/src/api.md

@@ -1,6 +1,6 @@
 # API
 
-The API of Agents.jl is defined on top of the fundamental structures  [`AgentBasedModel`](@ref), [Space](@ref Space), [`AbstractAgent`](@ref) which are described in the [Tutorial](@ref) page.
+The API of Agents.jl is defined on top of the fundamental structures [`AgentBasedModel`](@ref), [Space](@ref Space), [`AbstractAgent`](@ref) which are described in the [Tutorial](@ref) page.
 In this page we list the remaining API functions, which constitute the bulk of Agents.jl functionality.
 
 ## `@agent` macro
@@ -55,7 +55,6 @@ walk!
 get_direction
 ```
 
-
 ### Movement with paths
 For [`OpenStreetMapSpace`](@ref), and [`GridSpace`](@ref)/[`ContinuousSpace`](@ref) using [`Pathfinding.Pathfinder`](@ref), a special
 movement method is available.
@@ -108,8 +107,8 @@ rem_node!
 ```@docs
 OSM
 OSM.lonlat
-OSM.intersection
-OSM.road
+OSM.nearest_node
+OSM.nearest_road
 OSM.random_road_position
 OSM.plan_random_route!
 OSM.road_length
@@ -147,7 +146,7 @@ for id in ids_in_position((1, 1, 1, 1), model)
 end
 collect(allids(model))
 ```
-You will notice that only 1 agent got killed. This is simply because the final state of the iteration of `ids_in_position` was reached unnaturally, because the length of its output was reduced by 1 *during* iteration.
+You will notice that only 1 agent got killed. This is simply because the final state of the iteration of `ids_in_position` was reached unnaturally, because the length of its output was reduced by 1 _during_ iteration.
 To avoid problems like these, you need to `collect` the iterator to have a non dynamic version.
 
 **Lazy** means that when possible the outputs of the iteration are not collected and instead are generated on the fly.

examples/zombies.jl

@@ -55,8 +55,8 @@ function initialise(; seed = 1234)
         OSM.plan_random_route!(human, model; limit = 50) # try 50 times to find a random route
     end
     ## We'll add patient zero at a specific (latitude, longitude)
-    start = OSM.road((51.5328328, 9.9351811), model)
-    finish = OSM.intersection((51.530876112711745, 9.945125635913511), model)
+    start = OSM.nearest_road((51.5328328, 9.9351811), model)
+    finish = OSM.nearest_node((51.530876112711745, 9.945125635913511), model)
 
     speed = rand(model.rng) * 5.0 + 2.0 # Random speed from 2-7kmph
     zombie = add_agent!(start, model, true, speed)

src/models/zombies.jl

@@ -27,8 +27,8 @@ function zombies(; seed = 1234)
         OSM.plan_random_route!(human, model; limit = 50) # try 50 times to find a random route
     end
     ## We'll add patient zero at a specific (latitude, longitude)
-    start = OSM.road((51.5328328, 9.9351811), model)
-    finish = OSM.intersection((51.530876112711745, 9.945125635913511), model)
+    start = OSM.nearest_intersection((51.5328328, 9.9351811), model)
+    finish = OSM.nearest_node((51.530876112711745, 9.945125635913511), model)
 
     speed = rand(model.rng) * 5.0 + 2.0 # Random speed from 2-7kmph
     zombie = add_agent!(start, model, true, speed)

src/spaces/openstreetmap.jl

@@ -21,8 +21,8 @@ export test_map,
     road_length,
     plan_random_route!,
     lonlat,
-    intersection,
-    road,
+    nearest_node,
+    nearest_road,
     download_osm_network    # re-exported from LightOSM.jl
 
 
@@ -532,24 +532,25 @@ latlon(agent::A, model::ABM{<:OpenStreetMapSpace,A}) where {A<:AbstractAgent} =
     latlon(agent.pos, model)
 
 """
-    OSM.intersection(lonlat::Tuple{Float64,Float64}, model::ABM{<:OpenStreetMapSpace})
+    OSM.nearest_node(lonlat::Tuple{Float64,Float64}, model::ABM{<:OpenStreetMapSpace})
 
 Return the nearest intersection position to **(longitude, latitude)**.
-Quicker, but less precise than [`OSM.road`](@ref).
+Quicker, but less precise than [`OSM.nearest_road`](@ref).
 """
-function intersection(ll::Tuple{Float64,Float64}, model::ABM{<:OpenStreetMapSpace})
+function nearest_node(ll::Tuple{Float64,Float64}, model::ABM{<:OpenStreetMapSpace})
     ll = reverse(ll)
-    vert = Int(model.space.map.node_to_index[nearest_node(model.space.map, [GeoLocation(ll..., 0.0)])[1][1][1]])
+    nearest_node_id = LightOSM.nearest_node(model.space.map, [GeoLocation(ll..., 0.0)])[1][1][1]
+    vert = Int(model.space.map.node_to_index[nearest_node_id])
     return (vert, vert, 0.0)
 end
 
 """
-    OSM.road(lonlat::Tuple{Float64,Float64}, model::ABM{<:OpenStreetMapSpace})
+    OSM.nearest_road(lonlat::Tuple{Float64,Float64}, model::ABM{<:OpenStreetMapSpace})
 
 Return a location on a road nearest to **(longitude, latitude)**. Significantly slower, but more
-precise than [`OSM.intersection`](@ref).
+precise than [`OSM.nearest_node`](@ref).
 """
-function road(ll::Tuple{Float64,Float64}, model::ABM{<:OpenStreetMapSpace})
+function nearest_road(ll::Tuple{Float64,Float64}, model::ABM{<:OpenStreetMapSpace})
     ll = reverse(ll)
     best_sq_dist = Inf
     best = (-1, -1, -1.0)

test/jld2_tests.jl

@@ -292,8 +292,8 @@
             plan_route!(human, finish, model)
         end
 
-        start = OSM.road((51.530876112711745, 9.945125635913511), model)
-        finish = OSM.intersection((51.5328328, 9.9351811), model)
+        start = OSM.nearest_road((51.530876112711745, 9.945125635913511), model)
+        finish = OSM.nearest_node((51.5328328, 9.9351811), model)
         zombie = add_agent!(start, model, true)
         plan_route!(zombie, finish, model)
 

test/osm_tests.jl

@@ -14,18 +14,18 @@ using Graphs
     @test intersection[1] == intersection[2]
     @test intersection[3] == 0.0
     ll = OSM.lonlat(intersection, model)
-    @test intersection == OSM.intersection(ll, model)
+    @test intersection == OSM.nearest_node(ll, model)
 
     start_lonlat = (9.9351811, 51.5328328)
-    start_i = OSM.intersection(start_lonlat, model)
+    start_i = OSM.nearest_node(start_lonlat, model)
     i_diff = sum(abs.(OSM.lonlat(start_i, model) .- start_lonlat))
-    start_r = OSM.road(start_lonlat, model)
+    start_r = OSM.nearest_road(start_lonlat, model)
     r_diff = sum(abs.(OSM.lonlat(start_r, model) .- start_lonlat))
     @test i_diff >= r_diff
 
     finish_lonlat = (9.945125635913511, 51.530876112711745)
-    finish_i = OSM.intersection(finish_lonlat, model)
-    finish_r = OSM.road(finish_lonlat, model)
+    finish_i = OSM.nearest_node(finish_lonlat, model)
+    finish_r = OSM.nearest_road(finish_lonlat, model)
 
     add_agent!(start_r, model)
     plan_route!(model[1], finish_r, model)