Merge 74f26d6 into 959ac68

docs/Project.toml

@@ -0,0 +1,9 @@
+[deps]
+AutoViz = "82aa6e0c-a491-5edf-8d4b-c16b98e4ea17"
+AutomotiveDrivingModels = "99497e54-f3d6-53d3-a3a9-fa9315a7f1ba"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+Records = "5984c134-fa48-5ed5-a57f-fc2f6936871f"
+
+[compat]
+AutoViz = "^0.8.0"
+AutomotiveDrivingModels = "^0.7.11"

docs/src/Roadways.md

@@ -68,7 +68,6 @@ The Frenet frame is a lane relative frame to represent a position on the road ne
 
 ```@docs
       Frenet
-      get_posG
 ```
 
 ## Accessing objects and projections
@@ -117,4 +116,4 @@ such as lane or curve points:
 ```@docs
       Base.read(io::IO, ::MIME"text/plain", ::Type{Roadway})
       Base.write(io::IO, ::MIME"text/plain", roadway::Roadway)
-```
+```

docs/src/examples.md

@@ -0,0 +1,21 @@
+# Examples
+
+`AutomotiveDrivingModels` is templated to efficiently run simulations with different types of entities.
+An entity represents an agent in the simulation, and it is parameterized by
+
+- `S`: state of the entity, may change over time
+- `D`: definition of the entity, does not change over time
+- `I`: unique identifier for the entity, typically an `Int64` or `Symbol`
+
+In addition to the state, definition and identifier for each simulation agent,
+one can also customize the actions, environment and the driver models used by
+the agents.
+
+The following examples will showcase some of the simulation functionality of `AutomotiveDrivingModels`
+
+```@contents
+Pages = [
+    "examples/driving_in_circles.md",
+]
+
+```

docs/src/examples/driving_in_circles.md

@@ -0,0 +1,139 @@
+# Driving in Circles
+
+This example demonstrates a 2D driving simulation where cars drive around a three-lane stadium.
+The entities are defined by the types:
+
+- `S` - `VehicleState`, containing the vehicle position (both globally and relative to the lane) and speed 
+- `D` - `VehicleDef`, containing length, width, and class
+- `I` - `Symbol`, a unique label for each vehicle
+
+The environment is represented by a `Roadway` object which 
+allows to define roads consisting of multiple lanes based on the RNDF format.
+TODO: reference missing
+
+
+We load relevant modules and generate a 3-lane stadium roadway:
+
+```@example driving_in_circles
+using AutomotiveDrivingModels
+using AutoViz
+using Distributions
+
+roadway = gen_stadium_roadway(3)
+# TODO: use FitToContentCamera
+c = render([roadway]) # , camera=FitToContentCamera())
+write("stadium.svg", c) # hide
+write("stadium.png", c) # TODO: current interface also allows using this, DANGEROUS - change behavior
+```
+![three lane stadium](stadium.svg)
+
+As a next step, let's populate a scene with vehicles
+
+```@example driving_in_circles
+w = DEFAULT_LANE_WIDTH
+scene = Frame([
+    Entity(VehicleState(VecSE2(10.0,  -w, 0.0), roadway, 29.0), VehicleDef(), :alice),
+    Entity(VehicleState(VecSE2(40.0, 0.0, 0.0), roadway, 22.0), VehicleDef(), :bob),
+    Entity(VehicleState(VecSE2(70.0,  -w, 0.0), roadway, 27.0), VehicleDef(), :charlie),
+])
+car_colors = get_pastel_car_colors(scene)
+renderables = [
+    roadway,
+    (FancyCar(car=veh, color=car_colors[veh.id]) for veh in scene)...
+]
+# TODO: use FitToContentCamera
+render(renderables) # , camera=FitToContentCamera())
+write("stadium_with_cars.svg", render(renderables)) # hide
+```
+![stadium with cars](stadium_with_cars.svg)
+
+We can assign driver models to each agent and simulate the scenario.
+
+```@example driving_in_circles
+timestep = 0.1
+nticks = 300
+
+models = Dict{Symbol, DriverModel}()
+models[:alice] = LatLonSeparableDriver( # produces LatLonAccels
+    ProportionalLaneTracker(), # lateral model
+    IntelligentDriverModel(), # longitudinal model
+)
+# TODO: Tim2DDriver makes use of QueueRecord structure for scenes
+# see tim_2d_driver.jl line 47
+# see issue https://github.com/sisl/AutomotiveDrivingModels.jl/issues/62
+# models[:bob] = Tim2DDriver(
+#     timestep, mlane = MOBIL(timestep),
+# )
+models[:bob] = LatLonSeparableDriver( # produces LatLonAccels
+    ProportionalLaneTracker(), # lateral model
+    IntelligentDriverModel(), # longitudinal model
+)
+models[:charlie] = StaticDriver{AccelTurnrate, MvNormal}(
+    MvNormal([0.0,0.0], [1.0,0.1])
+)
+
+set_desired_speed!(models[:alice],   12.0)
+set_desired_speed!(models[:bob],     10.0)
+set_desired_speed!(models[:charlie],  8.0)
+
+scenes = simulate(scene, roadway, models, nticks, timestep)
+nothing # hide
+```
+
+An animation of the simulation can be rendered using the `Reel` package
+
+```@example driving_in_circles
+using Reel
+using Printf # hide
+
+camera = TargetFollowCamera(:alice; zoom=10.)
+
+animation = roll(fps=1.0/timestep, duration=nticks*timestep) do t, dt
+    i = Int(floor(t/dt)) + 1
+    update_camera!(camera, scenes[i])
+    renderables = [
+        roadway,
+        (FancyCar(car=veh, color=car_colors[veh.id]) for veh in scenes[i])...,
+        RenderableOverlay(IDOverlay(x_off=-2, y_off=1), scenes[i], roadway),
+        TextOverlay(text=[@sprintf("time: %.1fs", t)], pos=VecE2(40,40), font_size=24)
+    ]
+    render(renderables, camera=camera)
+end
+
+write("animated_stadium.gif", animation) # hide
+```
+
+![animated stadium with cars](animated_stadium.gif)
+
+Alternatively, one can also use the `Interact` framework to inspect the simulation record interactively.
+
+```julia
+using Interact
+@manipulate for step in 1 : length(scenes)
+    # , [IDOverlay()]  # TODO: add id overlay
+    render(scenes[step], roadway, camera=camera)
+end
+```
+
+The simulation results can be saved to a text file. We achieve this by first converting the list of scene to a `Trajdata` type and then exporting it.
+
+
+```julia
+listrec = Trajdata(timestep)  # TODO: there should be a constructor for Trajdata to do this directly, no?
+push!.(Ref(listrec), scenes)
+open("2Dstadium_listrec.txt", "w") do io
+    write(io, MIME"text/plain"(), listrec)
+end
+```
+
+The trajectory data file can be loaded in a similar way.
+
+
+```julia
+listrec2 = open("2Dstadium_listrec.txt", "r") do io
+    read(io, MIME"text/plain"(), Trajdata)
+end
+
+# TODO: maybe do something useful with the loaded data, like plot the speed over time or something
+```
+

docs/src/index.md

@@ -17,4 +17,15 @@ However it has been designed to support custom types.
 Each section of the documentation contains an interface, which is a list of functions that a user must implement to use its own types.
 
 ```@contents
+Pages = [
+    "Roadways.md",
+    "actions.md",
+    "states.md",
+    "agent_definitions.md",
+    "behaviors.md",
+    "simulation.md",
+    "collision_checkers.md",
+    "feature_extraction.md",
+    "examples.md",
+]
 ```

src/behaviors/sidewalk_pedestrian_model.jl

@@ -104,7 +104,7 @@ function update_approaching(ped::Entity{S, D, I},
 end
 
 function update_appraising(ped::Entity{S, D, I},
-                           scene::Scene,
+                           scene::Frame,
                            model::SidewalkPedestrianModel,
                            roadway::Roadway,
                            crosswalk::Lane,
@@ -140,7 +140,7 @@ end
 
 
 function update_crossing(ped::Entity{S, D, I},
-                         scene::Scene,
+                         scene::Frame,
                          model::SidewalkPedestrianModel,
                          roadway::Roadway,
                          crosswalk::Lane
@@ -158,7 +158,7 @@ end
 
 
 function update_leaving(ped::Entity{S, D, I},
-                        scene::Scene,
+                        scene::Frame,
                         model::SidewalkPedestrianModel,
                         roadway::Roadway,
                         sw_dest::Lane