Merge pull request #34 from mattuntergassmair/v0.8_camera_state

v0.8 camera state and improved default rendering

Project.toml

@@ -19,6 +19,7 @@ Vec = "44eeaf0b-fee4-471f-9310-ed6585cb3142"
 
 [compat]
 AutomotiveDrivingModels = ">=0.7.10"
+Colors = "=0.9.6"
 
 [extras]
 Interact = "c601a237-2ae4-5e1e-952c-7a85b0c7eef1"

README.md

@@ -30,32 +30,88 @@ Pkg.add(PackageSpec(url="https://github.com/sisl/AutoViz.jl"))
 
 ## Usage
 
-The main function is
+AutoViz works by adding rendering instructions to a `RenderModel`,
+and finally applying those instructions to a canvas using the
+`render` function.
+
+### Basic Usage
+
+In the simplest case, a `roadway` and a `scene` of types `Roadway` and `Scene`
+respectively can be rendered via
 
 ```julia
-render(scene)
+render([roadway, scene])
 ```
 
-where scene is an iterable of renderable objects including cars and roadways.
+However, the rendering interface is much more flexible than that,
+supporting custom rendering and cameras.
 
-Example:
-```julia
-roadway = gen_straight_roadway(3, 100.0)
-car = ArrowCar([50.0, 0.0], 0.0, color=colorant"blue") # [north, east], angle
-render([roadway, car, "some text"])
+### Renderable Objects
+
+In order for an object of type `ObjectType` to be "renderable",
+we need to provide a function with the signature
+``` julia
+    add_renderable!(rendermodel::RenderModel, obj::ObjectType)
 ```
+The basic example above works, because AutoViz implements the
+`add_renderable!` function for commonly used types such as
+`Roadway`, `Vehicle` or `Scene`.
+In general, the `render(renderables)` function can take any collection
+of renderable objects.
+AutoViz provides a series of convenient wrapper objects such as
+`FancyCar`, `FancyPedestrian`, `EntityRectangle` to make entities
+renderable.
 
-In a jupyter notebook, an image will appear, otherwise see the [Saving images](#saving-images) section below. A short tutorial is located in [notebooks/tutorial.ipynb](notebooks/tutorial.ipynb).
+### Cameras
 
-## Renderable
+A `Camera` object specifies what portion of the scene should be rendered.
 
-*What does it mean to be "renderable"?*
+By default, `render(renderables)` uses a static camera.
+In order to use an adaptive camera, the `camera` object
+needs to be updated before rendering and passed in to the
+`render` function as a keyword argument.
 
-An object is *directly renderable* if the function `render!(rm::RenderModel, object)` is implemented for it.
+```julia
+update_camera!(scene, camera)
+render([roadway, scene], camera=camera)
+```
 
-An object is *renderable by conversion* if `convert(Renderable, object)` returns a directly renderable object.
+### Full Example
+
+```julia
+# define roadway and vewhicle objects
+roadway = gen_straight_roadway(3, 100.0)
+lane = roadway[LaneTag(1,2)]
+def = VehicleDef(length=5., width=2.)
+ego = Entity(VehicleState(Frenet(lane, 50.,  0., 0.), roadway, 5rand()), def, :ego)
+carA = Entity(VehicleState(Frenet(lane, 20.,  2., -.2), roadway, 5rand()), def, :carA)
+carB = Entity(VehicleState(Frenet(lane, 40.,  -2., -.1), roadway, 5rand()), def, :carB)
+carC = Entity(VehicleState(Frenet(lane, 60.,  0., .4), roadway, 5rand()), def, :carC)
+carD = Entity(VehicleState(Frenet(lane, 80.,  3., .1), roadway, 5rand()), def, :carD)
+scene = Frame([ego, carA, carB, carC, carD])
+
+# define camera and adjust to scene
+camera = TargetFollowCamera(:ego; y=0., zoom=12.)
+update_camera!(camera, scene)
+
+# render
+renderables = [
+    roadway,
+    FancyCar(car=ego, color=colorant"blue"),
+    FancyCar(car=carA, color=rand(RGB)),
+    FancyCar(car=carB, color=rand(RGB)),
+    EntityRectangle(entity=carC, color=rand(RGB)),
+    EntityRectangle(entity=carD, color=rand(RGB)),
+    TextOverlay(text=["AutoViz rocks!"], font_size=60, pos=VecE2(400, 100), color=colorant"green")
+]
+for veh in scene
+    push!(renderables, VelocityArrow(entity=veh))
+end
+img = render(renderables, camera=camera)
+```
+
+In a jupyter notebook, an image will appear, otherwise see the [Saving images](#saving-images) section below. A short tutorial is located in [notebooks/tutorial.ipynb](notebooks/tutorial.ipynb).
 
-When `render()` is invoked, direct renderability is checked with `isrenderable(object)`, which defaults to `method_exists(render!, Tuple{RenderModel, typeof(object)})`. If this check fails, a conversion attempt is made with `convert(Renderable, object)`.
 
 ### Roadways and ArrowCars
 
@@ -140,6 +196,7 @@ All keyword arguments are optional. Objects of type `Renderable` now no longer h
  - Many setter functions for the camera have been replaced by the `set_camera!()` function which takes keyword arguments for `x`, `y` and `zoom`.
  - The implementations of `TargetFollowCamera` (former `CarFollowCamera`) and `SceneFollowCamera` have been reviewed and simplified. Additionally, a `ZoomingCamera` type which gradually changes the zoom level has been introduced and for easy extensibility there is also a `ComposedCamera` type which takes a list of cameras and applies their effects sequentially to the `RenderModel`.
  - The new `render!` function no longer takes a camera as an input argument, but assumes that the camera settings have already been applied to the `RenderModel` via `update_camera!` prior to calling `render!`. User code should be adapted accordingly.
+ - The `FitToContentCamera` is no longer available. To replace it, the method `camera_fit_to_content` is provided which computes camera parameters for which the entire content of the scene fits on the canvas. For most purposes, the `SceneFollowCamera` should be a good alternative.
 
 #### Visualization of Entities
  - Controlling the appearance of vehicles by setting `set_render_mode(:basic|:fancy)` is no longer encouraged. Instead, we provide new renderable types such as `EntityRectangle`, `FancyCar`, `FancyPedestrian`, `VelocityArrow` in addition to the already implemented `ArrowCar` type which can all be used to conveniently display entities.
@@ -148,7 +205,3 @@ All keyword arguments are optional. Objects of type `Renderable` now no longer h
 
 #### 1D Vehicles
  - Support for 1D vehicles has mostly been discontinued and some of the related functions were removed. However, the new functions should work seamlessly in many cases as long as the 1D vehicles implement basic functions such as `posg`, `width`, `length` from `AutomotiveDrivingModels.jl`
-
-## TODO: adapt tutorials
-## TODO: adapt unit tests
-## TODO: adapt docs

src/AutoViz.jl

@@ -38,20 +38,34 @@ export
     LIGHTTHEME,
     set_color_theme
 
+# Cameras
+include("cameras.jl")
+export
+    CameraState,
+    Camera,
+    update_camera!,
+    StaticCamera,
+    TargetFollowCamera,
+    ZoomingCamera,
+    ComposedCamera,
+    SceneFollowCamera,
+    FitToContentCamera,
+    set_camera!,
+    camera_fit_to_content!,
+    camera_move!,
+    camera_move_pix!,
+    camera_rotate!,
+    camera_zoom!,
+    reset_camera!
+
+
 include("rendermodels.jl")
 export
         RenderModel,
         render_to_canvas,
         add_instruction!,
-        camera_fit_to_content!,
-        camera_move!,
-        camera_move_pix!,
-        camera_rotate!,
-        camera_zoom!,
-        reset_camera!,
         reset_instructions!,
         reset_model!,
-        set_camera!,
         set_background_color!
 
 # Cairo drawing utilities
@@ -79,19 +93,6 @@ export
 
 include("fancy_render.jl")
 
-# Cameras
-include("cameras.jl")
-export
-    Camera,
-    update_camera!,
-    StaticCamera,
-    TargetFollowCamera,
-    ZoomingCamera,
-    ComposedCamera,
-    SceneFollowCamera,
-    FitToContentCamera
-
-
 # renderable interface
 include("renderable.jl")
 include("text.jl")