Merge pull request #43 from sisl/v0.8

[WIP] V0.8

.gitignore

@@ -1,4 +1,8 @@
 *.jl.cov
 *.jl.mem
 **/.ipynb_checkpoints
-docs/build/
+docs/build/
+*.webm
+test/*.svg
+test/*.png
+test/*.pdf

.travis.yml

@@ -3,10 +3,10 @@ language: julia
 sudo: required
 os:
   - linux
-  # - osx
+  - osx
 julia:
   - 1.0
-  - 1.3
+  - 1
 
 addons:
   apt:
@@ -30,11 +30,10 @@ jobs:
       julia: 1.0
       os: linux
       script:
+        - git clone https://github.com/JuliaRegistries/General  $(julia -e 'import Pkg; println(joinpath(Pkg.depots1(), "registries", "General"))')  
+        - git clone https://github.com/SISL/Registry  $(julia -e 'import Pkg; println(joinpath(Pkg.depots1(), "registries", "SISL"))')  
         - julia --project=docs/ -e 'using Pkg; Pkg.add("Documenter");
-                                               Pkg.add(PackageSpec(url="https://github.com/sisl/Vec.jl")); 
-                                               Pkg.add(PackageSpec(url="https://github.com/sisl/Records.jl")); 
-                                               Pkg.add(PackageSpec(url="https://github.com/sisl/AutomotiveDrivingModels.jl"));
-                                               Pkg.develop(PackageSpec(path=pwd())); 
+                                               Pkg.develop(PackageSpec(path=pwd()));
                                                Pkg.instantiate()'
         - julia --project=docs/ docs/make.jl
       after_success: skip

Project.toml

@@ -1,29 +1,32 @@
 name = "AutoViz"
 uuid = "82aa6e0c-a491-5edf-8d4b-c16b98e4ea17"
 repo = "https://github.com/sisl/AutoViz.jl.git"
-version = "0.7.10"
+version = "0.8.0"
+
 
 [deps]
 AutomotiveDrivingModels = "99497e54-f3d6-53d3-a3a9-fa9315a7f1ba"
 Cairo = "159f3aea-2a34-519c-b102-8c37f9878175"
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
-LightXML = "9c8b4983-aa76-5018-a973-4c85ecc9e179"
 Parameters = "d96e819e-fc66-5662-9728-84c9c7592b0a"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Records = "5984c134-fa48-5ed5-a57f-fc2f6936871f"
-Reel = "71555da5-176e-5e73-a222-aebc6c6e4f2f"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 Rsvg = "c4c386cf-5103-5370-be45-f3a111cca3b8"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Vec = "44eeaf0b-fee4-471f-9310-ed6585cb3142"
 
+[compat]
+AutomotiveDrivingModels = ">=0.7.10"
+
 [extras]
 Interact = "c601a237-2ae4-5e1e-952c-7a85b0c7eef1"
 NBInclude = "0db19996-df87-5ea3-a455-e3a50d440464"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Reactive = "a223df75-4e93-5b7c-acf9-bdd599c0f4de"
+Reel = "71555da5-176e-5e73-a222-aebc6c6e4f2f"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Interact", "NBInclude", "Random", "Reactive", "Test"]
+test = ["Interact", "NBInclude", "Random", "Reactive", "Reel", "Test"]

README.md

@@ -19,43 +19,90 @@ In julia 1.1+, the preferred way is to add the SISL registry and install AutoViz
 ] add AutoViz
 ```
 
-You can also manually add all the dependencies:
+## Usage
+
+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
-using Pkg
-Pkg.add(PackageSpec(url="https://github.com/sisl/Vec.jl"))
-Pkg.add(PackageSpec(url="https://github.com/sisl/Records.jl"))
-Pkg.add(PackageSpec(url="https://github.com/sisl/AutomotiveDrivingModels.jl"))
-Pkg.add(PackageSpec(url="https://github.com/sisl/AutoViz.jl"))
+render([roadway, scene])
 ```
 
-## Usage
+However, the rendering interface is much more flexible than that,
+supporting custom rendering and cameras.
+
+### 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.
+
+### Cameras
+
+A `Camera` object specifies what portion of the scene should be rendered.
 
-The main function is
+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.
 
 ```julia
-render(scene)
+update_camera!(scene, camera)
+render([roadway, scene], camera=camera)
 ```
 
-where scene is an iterable of renderable objects including cars and roadways.
+### Full Example
 
-Example:
 ```julia
+# define roadway and vewhicle objects
 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"])
+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).
 
-## Renderable
-
-*What does it mean to be "renderable"?*
-
-An object is *directly renderable* if the function `render!(rm::RenderModel, object)` is implemented for it.
-
-An object is *renderable by conversion* if `convert(Renderable, object)` returns a directly renderable object.
-
-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
 
@@ -115,3 +162,36 @@ using AutoViz
 set_color_theme(LIGHTTHEME)
 ```
 You can also define your own color theme using a dictionary. Look at the example in `src/colorscheme.jl` to have the correct key names.
+
+
+## Change Log
+
+### v0.8.x
+
+#### Rendering
+ - Clean-up of the rendering interface: there is now only one single rendering function with the signature
+```
+render!(rendermodel::RenderModel, renderables::AbstractVector; canvas_width::Int, canvas_height::Int, surface::CairoSurface))
+```
+All keyword arguments are optional. Objects of type `Renderable` now no longer have to implement the `render!` function (which is a misleading name). Instead one must implement the `add_renderable!` function which adds the rendering instructions to the `RenderModel`.
+ - Implicit conversions of non-renderable objects (such as `obj::Frame{Entity{S,D,I}}`) via implementations of `Base.convert(Renderable, obj)` are now discouraged. Instead, one can overwrite the `add_renderable!` method for such types. This is done for some very common types.
+ - The new `render!` function now only takes objects which are renderable, i.e. which implement the `add_renderable(rm::RenderModel, obj)` function. There is no longer a distinction between drawing roadways, scenes or overlays. They all need to satisfy the same interface, and they are drawn in the order in which they are passed to the `render!` function. This change decreases the number of available render functions from almost ten to one and should make the control flow more clear.
+ - Additional arguments to `render!` such as `camera` and `car_colors` are no longer supported. Camera effects should be applied before calling `render!` (see section below) and rendering attributes such as colors should be passed in as part of a renderable object.
+
+#### Overlays
+ - Changed the interface for rendering overlays to only take an instance of `RenderModel` and the overlay itself. All additional data must be stored as part of the overlay if it is needed during rendering.
+ - Added a `RenderableOverlay` wrapper which makes the legacy overlays work with the new rendering interface (in which overlays do not get any input arguments for rendering)
+
+#### Cameras
+ - Changed the camera interface. The full state of the camera, such as `camera_pos`, `camera_zoom`, `camera_rotation` is stored in `RenderModel` (this has already been the case in previous AutoViz versions). A `Camera` acts upon a `RenderModel` by changing these internal variables. The function `camera_set!` now becomes `update_camera!`.
+ - 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.
+
+#### 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.
+ - A convenience function for rendering scenes directly (i.e. without explicit conversion to a `Renderable` type) is still supported.
+ - TODO: make FancyCar work on my platform
+
+#### 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`

docs/Project.toml

@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.24"

docs/make.jl

@@ -1,8 +1,11 @@
-using Documenter, AutoViz
+using Documenter
+using AutoViz
 
-makedocs(modules = [AutoViz],
-         format = Documenter.HTML(),
-         sitename="AutoViz.jl")
+makedocs(
+    modules = [AutoViz],
+    sitename="AutoViz.jl",
+    format = Documenter.HTML()
+)
 
 deploydocs(
     repo = "github.com/sisl/AutoViz.jl.git"