Developer Manual

Martin Beck Sebastian Enderlein Marco Helmich Christian Holz Frank Huxol Nico Naumann David Rieck Bernd Schufele Jonas Trmper Martin Wolf Lutz Gericke Matthias Kleine Gerald Tpper Philipp Maschke Martin Czuchra

Contents
1 Introduction 2 Components 2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 8 8

3 Our Solution - eWorld 10 3.1 Development Environment Setup Guide . . . . . . . . . . . . . . 10 3.1.1 Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.1.2 Ant Build . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.1.3 Dealing with Dependency Problems . . . . . . . . . . . . 12 3.2 First Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2.1 Events To SUMO Converter / Events Integrator . . . . . 13 3.2.2 Automatic Route Generation . . . . . . . . . . . . . . . . 13 3.3 Graphical User Interface . . . . . . . . . . . . . . . . . . . . . . . 14 3.4 eWorld - Plugin Concept . . . . . . . . . . . . . . . . . . . . . . . 16 3.4.1 How to extend eWorld . . . . . . . . . . . . . . . . . . . . 17 3.4.2 How to consume an Extension Point while creating a new Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.5 Database Connection . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.5.2 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.5.3 Hibernate . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.5.4 Implementation . . . . . . . . . . . . . . . . . . . . . . . . 24 3.6 Simulation Visualizer . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.6.1 TraCI Interface . . . . . . . . . . . . . . . . . . . . . . . . 36 3.6.2 Visualization of Non-ModelElements . . . . . . . . . . . . 37 3.6.3 Visualization Workow . . . . . . . . . . . . . . . . . . . 37 3.7 Mini Map Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3.7.1 Implementation . . . . . . . . . . . . . . . . . . . . . . . . 38 3.8 eWorld - EventServer . . . . . . . . . . . . . . . . . . . . . . . . . 39 3.8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 3.8.2 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 39 3.8.3 Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 3.9 eWorld - Trac Light System . . . . . . . . . . . . . . . . . . . . 45 3.9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 45 3.9.2 Data Structure of Trac Lights in eWorld . . . . . . . . . 45 3.9.3 Trac Light Logic Generation . . . . . . . . . . . . . . . 46 3.9.4 Trac Light Menu . . . . . . . . . . . . . . . . . . . . . . 46 3

3.9.5 Export of Trac Lights . . . . . . . . . . 3.10 eWorld - Export to SUMO . . . . . . . . . . . . . 3.10.1 Introduction . . . . . . . . . . . . . . . . 3.10.2 Export of map data . . . . . . . . . . . . 3.10.3 Export of trac lights . . . . . . . . . . . 3.10.4 Export of events . . . . . . . . . . . . . . 3.10.5 Export of simulation data . . . . . . . . . 3.10.6 Export of dump conguration . . . . . . . 3.10.7 Summary . . . . . . . . . . . . . . . . . . 3.11 Car Editor . . . . . . . . . . . . . . . . . . . . . . 3.12 Importer . . . . . . . . . . . . . . . . . . . . . . . 3.12.1 Organisation of Importer Plug-Ins . . . . 3.12.2 OSM Importer . . . . . . . . . . . . . . . 3.12.3 SUMO Importer . . . . . . . . . . . . . . 3.13 Trac Light logic extraction . . . . . . . . . . . 3.13.1 Route File import . . . . . . . . . . . . . 3.14 Scenarios . . . . . . . . . . . . . . . . . . . . . . 3.14.1 Implementation . . . . . . . . . . . . . . . 3.15 Simulation Statistics . . . . . . . . . . . . . . . . 3.15.1 Collecting and importing simulation data 3.15.2 Managing statistical data in eWorld . . . 3.15.3 Visualizing statistical data . . . . . . . . . List of Figures List of Tables

. . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . .

47 48 48 48 49 50 51 52 52 53 54 54 56 56 57 57 58 58 59 60 60 62 65 67

Bibliography A Data Sources and Formats A.1 OpenStreetMap.org . . . . . . . . . . . A.1.1 Overview . . . . . . . . . . . . A.1.2 Advantages and Disadvantages A.1.3 Data Structure . . . . . . . . . A.1.4 Access Options . . . . . . . . . A.2 TIGER . . . . . . . . . . . . . . . . . A.2.1 Overview . . . . . . . . . . . . A.2.2 Advantages and Disadvantages A.2.3 Data Structure . . . . . . . . . A.2.4 Access Options . . . . . . . . . A.3 ESRI Shapele . . . . . . . . . . . . . A.3.1 Overview . . . . . . . . . . . . A.3.2 Advantages and Disadvantages A.3.3 Data Structure . . . . . . . . . A.3.4 Access Options . . . . . . . . . A.4 SUMO Formats . . . . . . . . . . . . . A.4.1 Overview . . . . . . . . . . . . A.4.2 Node File . . . . . . . . . . . . A.4.3 Edge File . . . . . . . . . . . .

67 70 70 70 70 71 72 72 73 73 74 74 75 75 76 76 78 78 79 79 79

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

A.4.4 Type File . . . . . . . . . . . . . . . . . . . . . . . . . . . B UML Models

80 82

C Legacy Features 87 C.1 eWorld - Export to VanetMobiSim . . . . . . . . . . . . . . . . . 87 C.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 C.1.2 Implementation . . . . . . . . . . . . . . . . . . . . . . . . 89

Chapter 1

Introduction
written by Martin Beck, Martin Czuchra

Welcome to the developer manual of eWorld, a framework to enrich mapping data with additional information, such as environment events like trac jams or icy areas, and provide this enhanced data to other applications, e.g. trac simulators. eWorld allows you to import mapping data in the OpenStreetMap (OSM) format either from les or directly from the according website. Imported data can be explored via translation and zooming. eWorld provides you with dierent information via several panels displaying details of hovered or selected items. Its main capability is to enrich imported data with environment events. Data manipulated this way can be exported to dierent simulators, a database or simply be saved in eWorlds own le format. In this manual you will nd information about how eWorld and its companions are implemented. First, chapter 2 gives an overview about eWorlds components. Chapter 3 nally reasons about archtictural design designs and implementation details. In the appendix A, several possible data sources and formats are presented and described. To gain a general understanding of how to dive into eWorld development, make sure to follow section 3.1 to set up your development environment and section 3.2 to learn about a few basic interactions in eWorld.

Chapter 2

Components
2.1 Overview
written by Tobias Queck

The simulation environment consists of a strictly separated component based architecture oering the possibility to replace each component implementation by another one implementing at least the same minimum requirements. All components are controlled and synchronized by a simulation management (see gure 2.1).

Figure 2.1: Software Simulation Environment (FMC Block Diagram) The central part builds the collection of virtual nodes realized with virtual machines. They are an essential dierence to other simulation environments. Virtualization technology will be used to get virtual nodes being as similar as possible to real VANET-nodes. The virtual node manager will base on a virtualization management system (see gure 2.1 - green) and will be adapted so that it is possible to deploy and undeploy virtual nodes automated and connect them using a simulated network. The simulated network will be generated by a network simulator (see gure 2.1 - blue) and will route messages between dierent virtual nodes. Additionally 8

this component will simulate all inuences related to wireless networks. Very important for wireless networks are the positions of the nodes because of the limited radio distance and the possible packet collisions. Therefore a realistic network topology is necessary which is based on the positions of the vehicle. The positions will be simulated by a trac simulator (Figure ?? - yellow) based on realistic trac ow models. The last component is the environment generator (see gure 2.1 - red). This component oers the possibility to generate a specic scenario in which the applications will be tested. Out of real roadmap data a location can be chosen and afterwards being enhanced by dynamic events. These events are road events like closed lanes, accidents, or closed roads and environment events like special weather conditions. The essential dierence of the proposed simulation environment compared with state of the art simulators is the use of the same applications which later on can be deployed in vehicles. Moreover these applications have a crucial inuence to the simulation. An application can change speed or directions of a vehicle triggered by sensor data or incoming messages, so that the whole trac ow and the corresponding network topology may be changed while the simulation is running. The simulation user is able to dene how many vehicles should participate in a simulation run, how many of these vehicles are able to route message, and how many of these have applications deployed. So the user is able to dene a dierent vehicle coverage which approximate dierent time periods after starting to sell V2X communication systems.

Chapter 3

Our Solution - eWorld

This section describes how to setup the eWorld project for development. The recommended way is to use Eclipse. You can however build the project with just Ant and the right properties les.

3.1.1

Eclipse

The eWorld project itself comes with an Eclipse project le, so it is very easy to import it into your own workspace. Choose Import from the Eclipse File menu and select General / Existing Projects Into Workspace. Afterwards you have to enter the path to your eWorld directory, where Eclipse will search for projects. When it was found, select it and click on Finish. Now eWorld appears as one of your projects. However, some additional work is needed. For getting eWorld to run correctly, Java 1.6 and JUnit 3.8.1 are needed. By now, these usually get delivered with your Eclipse installation and should be already included into the project after importing it. It is recommended to use the Java Virtual Machine from Sun as other implementations may signicantly decrease the performance. Note that your project needs to be named eWorld. If you downloaded the source from sourceforge the project probably needs to be renamed. Thats it, now you can start eWorld via the menu entry Run -> Open Run Dialog. A working run-conguration called Boot - eWorld should appear. Select it and press Run to start the graphical user interface of eWorld. Now you can start to enhance and extend the source code.

3.1.2

Ant Build

There is an ant le provided with your distribution of the eWorld source. Locate the "build.xml" in your eWorld folder. You can use this le to build a standalone distribution of eWorld as well as pruduction releases. Make sure to meet version requirements specied in 3.1.1. 10

To build a version of eWorld into your build folder, you have to create your own build.properties le. There is an example build.properties.default le in your source distribution that you may copy for that purpose. Trying to build eWorld without the properties le present will cause the build to fail. As dierent users do not have the same build environments, dont check in your properties le. To avoid accidental commits, the properties le is excluded from SVN version control. Make sure to provide a library folder in your build properties, as well as a source folder and a temporary folder. The temporary folder will be used to store class les and other plugin resources before each plugin is packaged into its own zip archive. The resulting built will be placed in what you specify to be the build folder. The following is an example conguration that will work with most environments: l i b . d i r=l i b tmp . d i r=tmp s r c . d i r=s r c b u i l d . d i r=b u i l d You should follow that denition by a list of plugins that you wish to build. You may choose to include and exclude specic plugins based on their package name, i.e. the following conguration builds the core plugin as well as the networkview plugin: i n c l u d e . p l u g i n s= de . h p i . e w o r l d . c o r e / / , de . h p i . e w o r l d . networkview / / Once youre set with your properties, check your environment by invoking the build info target: $ ant i n f o Youre expected to see an output similar to the one following. If versions are older, make sure to change your environment to meet minimum version requirements. B u i l d f i l e : b u i l d . xml info : [ echo ] [ echo ] [ echo ] [ echo ] B u i l d i n g p r o j e c t eWorld B u i l d f i l e . / b u i l d . xml Java v e r s i o n 1 . 6 Ant v e r s i o n Apache Ant v e r s i o n 1 . 7 . 1 c o m p i l e d on June 27 2008 [ echo ] B a s e d i r . BUILD SUCCESSFUL T o t a l time : 0 s e c o n d s To build the project according to your build properties, invoke: $ ant a l l The build process will build your eWorld version from source. Each plugin will be compiled and packaged separately, and the plugins will be placed in your 11

build folder, as congured in your properties le. The process will make sure to compile plugins in the right order to meet dependencies. It will also inform you that dependencies are not and cannot be met. This will cause your build to fail. When plugins are built successfully, remaining libraries and conguration les are copied to the build destination. To dive deeper into the build system, study the build.xml. When you run into problems with previously built les, you may use the clean target to eortlessly start building from scratch. Be aware that compiling all plugins will take some time, so avoid using this target before every build to save time. To invoke your newly built eWorld, change into your build folder and invoke $ j a v a j a r . / l i b / j p f boot . j a r

3.1.3

Dealing with Dependency Problems

Independently of whether you built your product with Eclipse, Ant, or both, you may run into dependency problems within your plugins. While the Ant build actually checkt plugin descriptors for consistency, you might nd that Eclipse is not as strict with access to the classpath once the plugin is loaded. To check for integrity without actually building the product, you may use the integrity-check target with Ant. See 3.1.2 for requirements you have to meet beforehand. However, any default Ant build will, when failing, not tell you exactly what the problem with your descriptors is. To nd the problem you want to x, not only that there is one, you may use the verbose-integrity-check target. This target will also take into account the order in which requirements should be met when checking plugins. The output is quite verbose, and an error in one plugin will not cause the build to stop. It will continue, until all checks are complete, showing you a summary at the end. This is the result of a successful verbose integrity check: $ ant v e r b o s e i n t e g r i t y check B u i l d f i l e : b u i l d . xml checkp r e r e q u i s i t e s : [ echo ] Loading JPF t a s k s . . . [ echo ] Loading AntC o n t r i b t a s k s . . . prerequisites : init : v e r b o s e i n t e g r i t y check : [...] [ j p f check ] s e v e r i t y=INFO ; code= NO_ERROR; message=checked 0 e x t e n s i o n s f o r de . h p i . e w o r l d . core@0 . 8 . 3 ; source={ P l u g i n D e s c r i p t o r : u i d=de . h p i . e w o r l d . core@0 . 8 . 3 } [ j p f check ] s e v e r i t y=INFO ; code= NO_ERROR; message=plugi n de . h p i . e w o r l d . core@0 . 8 . 3 checked ; source={ P l u g i n D e s c r i p t o r : u i d=de . h p i . e w o r l d . core@0 . 8 . 3 } [ j p f check ] s e v e r i t y=INFO ; code= NO_ERROR; message=20 plugi n s checked ; 12

source=n u l l [ j p f check ] REPORT END [ j p f check ] I n t e g r i t y check done . E r r o r s : 0 . Warnings : 0 . [ echo ] Checked i n t e g r i t y . BUILD SUCCESSFUL T o t a l time : 0 s e c o n d s When your check fails, you will have to sort out errors that were emitted during the process. Once complete, invoke the check again and make sure that everything works ne.

3.2

First Steps

The following sections describe simple programs developed during the projects iterations. They mainly cover converter scripts to map dierent data formats needed by simulators and oered by data providers.

3.2.1

Events To SUMO Converter / Events Integrator

Events2SUMO is a collection of python scripts to integrated events (environment events and road events) into an existing SUMO [DK] road map. Furthermore, Events2SUMO writes new environment events to a PostgreSQL database and provides interface classes to enable the Sensor Interface to query events close to the vehicles current position.

3.2.2

Automatic Route Generation

Overview This section describes the generation of routes with SUMO. Every vehicle in SUMO has its own route predened in an routes-XML-le. As well as the single travel points of the route, it also includes a time index, indicating when the vehicle described via the route will start driving. The exact format is irrelevant, because it can be generated via several SUMO tools. The simplest solution is a full random route generation. Random Route Generation Generating random routes is a very basic way to create a routes-le for SUMO. The advantage is its easiness, but the clear disadvantage is, that it does not reect the real world. Usually, more cars drive on major roads rather than on minor roads. SUMO provides two tools, DUAROUTER and JTRROUTER, to generate random routes. They both take the same arguments but use dierent algorithms. Important values are the number of randomly generated vehicle routes 13

per time step and the interval in which the cars should be emitted. One problem with this method is, that networks which have gaps inbetween or not connected subnetworks, result in errors. If the option continue-on-unbuild is set, the generator will omit erroneous routes, but continue with further routes. For testing purposes, the internal pseudo-random number generators are always initialized with the same seed. Thus, the abs-rand -option has to be provided to achieve completely random routes each time. duarouter -n <FILE> -R <NUMBER> -o <FILE> --abs-rand \ -b <NUMBER> -e <NUMBER> --continue-on-unbuild jtrrouter -n <FILE> -R <NUMBER> -o <FILE> --abs-rand \ -b <NUMBER> -e <NUMBER> --continue-on-unbuild parameter -n <FILE> -R <NUMBER> -o <FILE> -b <NUMBER> -e <NUMBER> continue-on-unbuild abs-rand meaning the SUMO network le to read number of cars per to generate per timestep output le, where routes are written to starting time for emitting vehicles end time for emitting vehicles if an error is found, continue generating routes use completely random numbers

Table 3.1: DUAROUTER/JTRROUTER random generation arguments

3.3

Graphical User Interface

The eWorld application and environment is glued by several dierent components. A very important one is the graphical user interface. It is used for importing OSM road networks into the eWorld database and enriching them with dierent environment events like rain, accidents or trac jams. After setting up those events with their positions, time frames, etc. data can be exported to the trac simulator SUMO, which in turn take over the simulation part. The GUI of eWorld is programmed using the Swing library of Java [Sun] and the Scenario library [Sce]. This ensures fast and consistent graphical widgets on every major platform, i.e. Windows, Mac OS X and Linux. In contrast to other GUI libraries for Java like Qt, the Swing library is part of Java itself and the development of the Scenario library isnt stopped like it is the case of Qt-Jambi. It still enables us to write a sophisticated user interface using decoupled widgets via an observer notication mechanism and other well documented features of Swing. As the GUIs main task is to display road network and environment information and provide means to enrich these with new entities, eWorld centers around the plugin networkview. This plugin is responsible for displaying items like roads, crossings or environment events such as fog. In order to do this, it 14

contains a hierarchy of items duplicating the data model illustrated in gure 3.5. This GUI model can be found in the package de.hpi.eworld.networkview.model. The network view widget uses the Scenario Framework. This framework aims at providing a full-featured 3D drawing facility. That perfectly suits our needs, because we want to put custom items like roads in a scene, draw them and be able to manipulate them. Figure 3.1 shows the general structure: A JSGPanel is set up on some SGGroups which contains multiple SGNodes, i.e. it is the data model for the view. NetworkView inherits from JSGPanel and adds some behavior for catching drag and drop actions, zooming and especially item handling. The NetworkView gets informed about every single item, which gets added, removed or changed to the database model, so it can update the graphical representation.
Observer JComponent SGNode * MouseListener JSGPanel 1 * SGParent SGLeaf

NetworkView

SGGroup

AbstractItem

Figure 3.1: NetworkView in context of the Scenario framework Another important task of the NetworkView is to handle the level of detail. As a map is zoomed out more and more, some of the items will be not displayed anymore or the graphical representation of these items gets more and more abstracted. As this abstraction is part of the implementation of the specic ViewItem, the hiding and showing of items is task of the NetworkView. For example the NodeItems will be hidden at a very near zoom level to enhance the display performance. The scene that the NetworkView manages consists of two separate domains: Events and the road network. Figure 3.2 presents the classes involved in road rendering. The hierarchy duplicates the model class tree to some extent, because these classes must inherit SGNode and thus cannot also inherit and extend the data model classes. This results from Java being a single-inheritance language. The NetworkView uses several classes to display the ModelElements in the ModelManager. All these classes inherit from the abstract base class AbstractItem, which itself extends the Scenario classes SGNode and SGLeaf. The class ViewItem inherits from AbstractItem for historical reasons and is the abstract base class class for all items, which are displayed via the NetworkView. One major class is the WayItem. Each WayItem on the map represents a Way in the ModelManager. For these items a very sophisticated implementation was neccessary, because they are a central interaction point in the graphical user interface of eWorld. One major feature of this class is the support of level of detail. This is accomplished by using a well-known algorithm for line abstraction, the Douglas-Peucker-Algorithm1 . This algorithm was especially enhanced to work best with eWorld.
1 Douglas-Peucker-Algorithm

[Dou]

15

<<interface>> HoverItem AbstractItem

ViewItem

WayItem

Annota8onItem

PointOfInterestItem

TracLightItem

Figure 3.2: Road network model for GUI AnnotationItem is a superclass for items, which can be placed in the world view and annotate their positions with additional data like some point of interest or a trac light. All road network items implement the HoverItem interface, which indicates, that a view item is hoverable. If the mouse moves and a hoverable element is at the mouse position, the element is marked as hovered resulting in another color for the item or similiar modications. This is dened by the items themselves. EventItems are also AnnotationItems as gure 3.3 shows, because they annotate their position with event data such as fog, rain or accidents. There are two types of EventItems: One item for road events and two for environment events.

3.4

eWorld - Plugin Concept

From version 0.6 on, eWorld completely bases on the Java plug-in framework [jpf]. This architectural change shall enable every developer to adapt and integrate eWorld into their simulation environment easily. Since JPF allows to entirely compose applications out of plug-ins, almost every piece of functionality turned into an own plug-in. The new architecture allows developers to not only build on top of eWorld but also allows them to enrich core features of eWorld by adding new (or even replace) plug-ins. This way eWorld became more polymorphic and exible. The new plug-in architecture reduces the scope and complexity for enhancements by embedding a potential new feature into a plug-in context in which the new plug-in does not have to care about where to dock on and how to exchange data. Enhancements are made just by nding the right extensions points and exposed classes. To reduce the complexity of nding the right extension points to dock on and allow better insights which service is provided by which plug-in, a plug-in catalogue is about to be introduced. The 16

AbstractItem

ViewItem

Annota1onItem

EventItem

RoadEventItem

EnvironmentEventItem

PolygonEventItem

CircleEventItem

Figure 3.3: Event model for GUI

catalogue gives a description of every plug-in and explains its extension points and oered services. Additionally, the catalogue contains a plug-in map in which relationship between plug-ins are illustrated. This section shall give any developer the possibility to immediately start to extend eWorld. It starts with an introduction in the most basic terms and concepts of JPF and concludes in a hands-on manual how to extend eWorld. Since the JPF is still under development, please see the JPF homepage 2 for up-to-date information.

3.4.1

How to extend eWorld

In order to oer any kind of functionality, an extension point needs to be declared and implemented (since a plug-in in JPF consists of two dierent parts: the manifest le and the plug-in specic Java code). This section is mostly concerned with providing an extension point whereas the next section is all about creating a new plug-in and consuming an extension point. An extension point is a bi-directional communication interface. This communication involves two parties one party that oers an extension point (host plug-in) and the second consumes this extension point (consuming plug-in). This does not mean that an extension point can only be consumed once. Within this plug-in concept, the extension point oering plug-in always calls the extension point consuming plug-in.
2 jpf.sourceforge.net

17

Plug-in Manifest A plug-in manifest is an XML syntax le created according to the plug-in DTD 3 . In order to declare a new extension the following XML code has to be pasted under to root of the according plugin.xml. <e x t e n s i o n p o i n t i d=" I m p o r t P r o v i d e r "> <parameterd e f i d=" c l a s s " /> <parameterd e f i d=" a c t i o n " /> <parameterd e f i d=" d e s c r i p t i o n " m u l t i p l i c i t y=" noneorone " /> </ e x t e n s i o n p o i n t> The extension point element exposes the specication of a new extension point to any other plug-ins. An extension point consists of an id and denes parameters that need to be passed to the host plug-in. Any plug-in that contributes to this extension point has to provide these parameters that will be used to present the according plug-in and communicate with it. We dene three parameters for this extension point: class This is a required parameter of type String that should contain the full Java class name. action The name of tool to be shown as "tab name" on GUI. description The description is shown as tool tip while hovering the item in the menu bar. To make the extension point discoverable, the according Java interface has to be exported to all other plug-ins. <runtime> < l i b r a r y i d=" i m p o r t e r " path=" c l a s s e s / " type=" code "> <e x p o r t p r e f i x=" " /> </ l i b r a r y> </ runtime> To ensure that your plugin manifest is still valid, you may use the verboseintegrity-check build target as described in Section 3.1.3. Plug-in Code This section is all about the code that is needed to make a new extension point y. Here is explained how hosting plug-ins bind consuming plug-ins and use them. After the activation of the host plug-in this code runs in order to search, bind, and start implementing extensions. public void i n i t i a l i z e I m p o r t e r P l u g i n s (QMenu rootMenu ) { E x t e n s i o n P o i n t importExtPoint = getManager ( ) . g e t R e g i s t r y ( ) . g e t E x t e n s i o n P o i n t ( g e t D e s c r i p t o r ( ) . g e t I d ( ) , IMPORTER_EXTPOINT_PROVIDER) ;
3 http://jpf.sourceforge.net/dtd.html

18

f o r ( E x t e n s i o n e x t : importExtPoint . g e t C o n n e c t e d E x t e n s i o n s ( ) ) { try { // Get p l u g i n c l a s s l o a d e r C l a s s L o a d e r c l a s s L o a d e r = getManager ( ) . g e t P l u g i n C l a s s L o a d e r ( ext . getDeclaringPluginDescriptor ( ) ) ; // Load c l a s s C l a s s <?> i m p o r t C l s = c l a s s L o a d e r . l o a d C l a s s ( e x t . get Par ame ter ( " c l a s s " ) . v a l u e A s S t r i n g ( ) ) ; // C r e a t e i n s t a n c e ImportProviderInterface importProvider = ( ImportProviderInterface ) importCls . newInstance ( ) ; // I n i t i a l i z e c l a s s i n s t a n c e a c c o r d i n g t o i n t e r f a c e c o n t r a c t i m p o r t P r o v i d e r . i n i t ( rootMenu ) ; } catch ( Throwable t ) { displayPluginLoadErrorMsg ( t , ext ) ; } } } Now the Java interface which denes the extension point needs to be created. package de . h p i . e w o r l d . i m p o r t e r ; import com . t r o l l t e c h . qt . g u i . QMenu ; public i n t e r f a c e I m p o r t P r o v i d e r I n t e r f a c e { public void i n i t (QMenu topMenuElement ) ; } This interface species only one method which is used to pass the menu item for importers to consuming plug-ins. With these preparations an extension point is specied and declared. Now a new plug-in can dock on it.

3.4.2

How to consume an Extension Point while creating a new Plug-in

This section describes how to create a new plug-in and dock on the just dened extension point. In order to create a new plug-in, a new source folder in the eWorld home directory needs to be created. The naming convention for plug-ins foresees that the created folder is named like plugins/<unique plug-in id>/source. In our case the folder is named plugins/de.hpi.eworld.importer.le/source. In this source folder, a new Java package shall be created which is named after the unique plug-in id. The folder contains all resources that are necessary to start the plug-in such as the plugin.xml and probably a folder for images or required libraries. The Java package contains all source code les. 19

After that the just created folder needs to be added to the projects build path. Also very important is that the output folder for the plug-in is changed to eWorld/plugins/<unique plug-in id>/classes. In the end the dialog should look like illustrated in Figure 3.4.

Figure 3.4: Conguration of the Projects Build Path Now you are ready to begin the actual development of the plug-in. Keep in mind that we want to dock on the previously exposed extension point and this way add new functionality to eWorld. Plug-in Code After resolving dependencies, all plug-ins are searched and (on-demand) started. Each plug-in need an entry point where the execution begins. Within JPF, such a class extends org.java.plugin.Plugin. org.java.plugin.Plugin contains two abstract methods protected void doStart() and protected void doStop(). doStart is called immediately after the activation of the plug-in and can therefore seen as a public void main of a JPF plug-in. doStop is called shortly before the plug-in is shut down. An empty starting point for a plug-in might look like this. package de . h p i . e w o r l d . i m p o r t e r . f i l e ; import import import import import import org . java . plugin . Plugin ; com . t r o l l t e c h . qt . c o r e . QUrl ; com . t r o l l t e c h . qt . g u i . QAction ; com . t r o l l t e c h . qt . g u i . QIcon ; com . t r o l l t e c h . qt . g u i . QMenu ; de . h p i . e w o r l d . c o r e . MainWindow ;

public c l a s s OsmFileImportPlugin extends P l u g i n { 20

public s t a t i c f i n a l S t r i n g PLUGIN_ID = " de . h p i . e w o r l d . i m p o r t e r . f i l e " ; @Override protected void d o S t a r t ( ) throws E x c e p t i o n { // your code h e r e } @Override protected void doStop ( ) throws E x c e p t i o n { // your code h e r e } private void doVoodoo ( ) { // do somethin magic } } After a plug-in is activated, it behaves like every other Java application. As mentioned before, we want to dock on the previously dened extension point. In order to do that we need to implement the Java interface which represents the extension point programmatically. package de . h p i . e w o r l d . i m p o r t e r . f i l e ; import import import import import o r g . apache . l o g 4 j . Logger ; org . java . plugin . P l u g i n L i f e c y c l e E x c e p t i o n ; o r g . j a v a . p l u g i n . PluginManager ; com . t r o l l t e c h . qt . g u i . QMenu ; de . h p i . e w o r l d . i m p o r t e r . I m p o r t P r o v i d e r I n t e r f a c e ;

public c l a s s OsmFileImportProvider implements I m p o r t P r o v i d e r I n t e r f a c e { public void i n i t (QMenu menu ) { PluginManager pManager = PluginManager . lookup ( t h i s ) ; OsmFileImportPlugin p l u g i n = null ; try { p l u g i n = ( OsmFileImportPlugin ) pManager . g e t P l u g i n ( OsmFileImportPlugin . PLUGIN_ID ) ; } catch ( P l u g i n L i f e c y c l e E x c e p t i o n e ) { Logger l o g = Logger . g e t L o g g e r ( t h i s . g e t C l a s s ( ) ) ; log . e r r o r ( " Error while i n i t i a l i z i n g . . . " , e ) ; } p l u g i n . i n i t i a l i z e M e n u ( menu ) ; } }

21

Plug-in Manifest To make the new plug-in discoverable, it needs a plug-in manifest. The root tag of such an XML is: <p l u g i n i d=" de . h p i . e w o r l d . i m p o r t e r . f i l e " version=" 0 . 6 " c l a s s=" de . h p i . e w o r l d . i m p o r t e r . f i l e . OsmFileImportPlugin "> Here is stated that the plug-in ID is de.hpi.eworld.importer and the version number is set to 0.6. We also declare that our plug-in has a plug-in class which is named de.hpi.eworld.importer.ImporterPlugin so that the JPF runtime can initialize the plug-in properly. The plug-in class is an optional element of the plug-in declaration and can be omitted if your plug-in doesnt need any code to be executed during plug-in activation. But in this case the plug-in needs to execute code after it was activated. The rst manifest element species which other plug-in is needed: <r e q u i r e s> <import p l u g i n i d=" de . h p i . e w o r l d . i m p o r t e r " /> </ r e q u i r e s> Within the enclosing requires tag all plug-ins are listed as indicated above. The next manifest element is the declaration of required libraries and resources: <runtime> < l i b r a r y i d=" i m p o r t e r . f i l e " path=" c l a s s e s / " type=" code " /> < l i b r a r y type=" r e s o u r c e s " path=" images / " i d=" images " /> </ runtime> Here is dened that all Java code from this plug-in is placed into classes/ folder within the plug-ins home folder. We also declare that all classes and packages (*) from this plug-in are visible to other plug-ins so that they can use the code freely. We also declare a resources folder icons/ and also made it visible to other plug-ins. The next element denes that this plug-in is an extension of a certain extension point.

<e x t e n s i o n p l u g i n i d=" de . h p i . e w o r l d . i m p o r t e r " p o i n t i d=" I m p o r t P r o v i d e r " i d=" OsmFileImportProvider "> <parameter i d=" c l a s s " v a l u e=" de . h p i . e w o r l d . i m p o r t e r . f i l e . OsmFileImportProvider " / <parameter i d=" a c t i o n " v a l u e=" Import " /> <parameter i d=" d e s c r i p t i o n " v a l u e=" Imports OSM data from f i l e " /> </ e x t e n s i o n> Here is stated that this plug-in extends the extension point ImportProvider (see point-id) of the plug-in de.hpi.eworld.importer (see plugin-id). In order to make these two parties t together the required parameters have to be passed over. The parameter class species the class that implements the Java interface of this extension point. This class is handed over to the host plug-in (see Listing 3.4.1). JPF can now perform integrity checks and throw warnings or errors if the declarations miss something. And with that, we are good to go. Congrats! You wrote your rst plug-in. Now start up eWorld and see it work. 22

3.5
3.5.1

Database Connection
Overview

This section describes the eWorld database connection plugin. With this plugin, map data that has been imported into eWorld, and event data that was created in eWorld, can be exported into a database. The data can also be restored from the database and displayed in the GUI.

3.5.2

Architecture

The database connection plugin consists of two main classes, DatabaseCongDialog and DatabaseAccess. They are all organized in the package de.hpi.eworld.db in the database plugin. DatabaseAccess is the class, which saves the data model the database and restores from there. Moreover, the database schema can be created automatically in an empty database. DatabaseCongDialog provides a graphical dialog to set the URL of the database server, the port on which the server is running, the user name and the password of the database user.

3.5.3

Hibernate

For the persistence of the Java objects, we use the framework Hibernate [hib]. Hibernate allows to persist and load objects without the usage of SQL. Therefore the database can be exchanged easily, because Hibernate abstracts from the SQL dialect of the underlying database. Hibernate only deals with objects. The mapping of the classes to database tables has to be dened once declaratively. This can be done in an XML le or with annotations in the Java classes themselves. Therefore, the persistence layer does not have to deal with the relational database model. The basic concept of Hibernate are sessions. Sessions provide an additional cache, which lays between the application and the database. Objects can be bound to a session. In order to do that, rst a transaction has to be opened. With the method s e s s i o n . s a v e ( Object o ) the object is bound to the session. This does not mean yet, that the object is stored in the database. The saving begins, when the transaction is committed or the session is ushed with the method session . flush () Persisted objects get assigned an identication number. When an object is bound to a session and the object already has an identier assigned, Hibernate assumes, that the object is already persisted. If the object in fact is not persisted, Hibernate might try to update these objects, which leads to errors. Later on it will be explained, where this issue occured in the implementation of the database plugin. Another possibility to bind an object to a session is to recreate the object from the database. There are two possibilities to do that. Either by calling the method 23

s e s s i o n . load () or with the Hibernate Query Language (HQL). There are several overloaded versions of the load method, but all have in common that the identication number of the object is required. As in eWorld data shall also be restored from previous usages of the program, and hence the identication number is not available, s e s s i o n . load () is not suitable for our purposes. Moreover, each object is loaded with a separate SQL query of the form SELECT F O table W E E i d = x R M HR Obviously, this is not very performant in comparison to a single query SELECT F O table R M However, with HQL individual queries can be built. The syntax of HQL is similar to the one of SQL, but HQL addresses classes, not tables. With the query F O Classname R M all persisted objects of the given class are loaded from the database. A query can be created with the method Query s e s s i o n . c r e a t e Q u e r y ( S t r i n g query ) and can be executed with the method query . l i s t ( ) This method returns a list of all the objects that are loaded. The actual loading from the database only happens, when the session is ushed, the transaction is commited or the object is used. As long as an object is bound to a session and the session is open, it is controlled by Hibernate. This means, that changes of attributes are registered and on a ush, they are saved in the database. In the declarative mapping of the classes to tables, it can also be dened, that relations between classes are persisted transparently. This means, when an object is saved, its attributes, which are objects are also persisted.

3.5.4

Implementation

Mapping In order to have the mapping of the classes to database tables directly in the classes, we used Hibernate Annotations. Thereby only general parameters, such as the JBDC driver the to be used or the SQL dialect of the database are specied in a central XML conguration le. The mapping of classes to tables and associations to columns or association tables is denoted in the implementation of the class, directly with the class and attribute declarations. All classes in the packages de.hpi.eworld.model.db.data and de.hpi.eworld.model.db.data.event are persisted. In all classes, the header for Hibernate looks almost identical. Here the header of the class Way is illustrated exemplarily: 24

@Entity @Table ( name=" ways " ) @SequenceGenerator ( name="SEQ_WAY" , sequenceName=" ways_id_seq " ) public c l a s s Way extends ModelElement implements S e r i a l i z a b l e The @Entity annotation just indicates, that this is a class, which can be persisted. In which table the class is persisted, is specied by the @Table annotation. The id for each database entry, i.e. for each object, can be generated automatically by the database. This guarantees, that there only unambiguous identiers. In our database model, each table that represents a class has an own sequence generator to create the identiers. An internal name, which can be used to inside the Java class must be assigned to each sequence generator with the annotation @SequenceGenerator. Here, the sequence generator of the database table ways is called ways_id_seq and the name SEQ_WAY is assigned to it and can be used in this class. As classes can inherit from other classes, and hence can have attributes, which are not explicitly dened in the class itself, but inherited from the parent class, inherited classes must be treated dierently. Hibernate supports several strategies to map inheritance onto tables. The strategy that we used is called joined subclasses. This means, that for each class in the inheritance tree, there is a single table. As a consequence of this, the attributes of an inherited class are spread over several tables. Each table contains exactly the attributes, which are dened in the corresponding class. So, the attributes of a class B that inherits from class A are partially in the table of class A. In order to restore objects of inherited classes correctly, the same identier of the object is used as primary key in the tables for class A and class B. When restoring the objects, only a join over the primary keys has to be executed. Hibernate must be informed about the inheritance strategy. Therefore, in the parent class an additional annotation must be added. This is done with the annotation @Inheritance. For example, the class Node, which is inherited by the class TracLight has the following header: @Entity @Table ( name=" nodes " ) @ I n h e r i t a n c e ( s t r a t e g y=I n h e r i t a n c e T y p e . JOINED) public c l a s s Node extends AbstractNode implements S e r i a l i z a b l e An attribute of each class must be specied to contain the identier of the object. In our implementation, this attribute is declared in every class as private int i d ; The above mentioned sequence generator must be assigned to this variable. How this is done is also shown here exemplarily for the class Way: @Id @GeneratedValue ( s t r a t e g y=GenerationType .SEQUENCE, g e n e r a t o r="SEQ_WAY" ) public int i d ; 25

There are four major types of associations, which can be declared with Hibernate: one-to-one, one-to-many, many-to-one and many-to-many. One-to-one associations can always be mapped in the table, which belongs to the class, in which the attribute is declared or in the the table of the target class. In all one-to-one associations that exist in the eWorld data classes, the association was always mapped in the table of the class that contains the attribute. This is done by an additional column that holds the identier of the target object. This example shows an attribute that represents a OneToOne association of the class Event to the class Location: @OneToOne( f e t c h=FetchType .EAGER) @JoinColumn ( name=" l o c a t i o n " ) protected L o c a t i o n l o c a t i o n ; The @OneToOne annotation indicates the type of the association. FetchType.Eager signies, that the associated object is loaded immediately, when the containing object is restored from the database. Another option would be FetchType.LAZY, where the associated object is rst loaded, when it is required. As for this the Hibernate session must be left open all the time, it was not suitable for our purpose and hence the eager loading mode is used everywhere. With @JoinColumn it can be specied, which column of the table holds the foreign key to the entry of the associated object. One-to-many associations must always be mapped to the target class table. The table, which represents the class of the attribute, must have an additional column, which contains a foreign key to the table with the data of the class, in which the attribute is declared. A typical one-to-many Hibernate declaration looks like this one in the class Edge: @OneToMany( f e t c h=FetchType .EAGER) @JoinColumn ( name=" edge " ) @IndexColumn ( name = " i n d e x i n e d g e " , b a s e =0) private L i s t <Lane> l a n e s ; The @OneToMany annotation determines the type of the association. With FetchType.EAGER, like described above, the associated objects are restored, when the containing object is restored. With @JoinColumn, in contrast to the one-to-one association, here a column in the table of the target class is specied. As associated objects of one-to-many associations are usually stored in collections, such as a list, the objects might be ordered. Therefore, an index column can be specied with the annotation @IndexColumn. The index column is also located in the table of the associated class and contains the index of the element in the collection, in which it is stored. Besides, the base number of the index can be specied, in eWorld always 0 is chosen. Many-to-one associations have to be be stored in the class that contains the attribute of the association. This is done with an additional column, that contains a foreign key to the table of the associated class. Another example of the class Edge shows a many-to-one association to the class Node: @ManyToOne( f e t c h=FetchType .EAGER) @JoinColumn ( name=" fromnode " ) private Node fromNode ; 26

The @ManyToOne annotation declares the type of the association, the fetch type is specied as for one-to-one and many-to-one associations. With @JoinColumn, like in one-to-one associations, a column in the table of the class that contains the associations is specied, which holds a foreign key to the table of the associated class. The associations that are the most dicult to map are many-to-many associations. As both, objects of the containing class and the of target class are potentially associated with more than one objects of the other class, the association cannot be mapped with a single column in one of the corresponding tables. Hence an additional table for the mapping of the association is required. The association table has two columns, one with a foreign key to the containing class, and one with a foreign key to the target class of the association. How a many-to-many association is declared with Hibernate describes this example of the class Traclight: @ManyToMany( f e t c h=FetchType .EAGER) @JoinTable ( name=" w a y _ t r a f f i c l i g h t " , joinColumns={@JoinColumn ( name=" t r a f f i c l i g h t " ) } , i n v e r s e J o i n C o l u m n s={@JoinColumn ( name="way" ) } ) @IndexColumn ( name = " i n d e x i n t r a f f i c l i g h t " , b a s e =0) The type of the association is specied with the @ManyToMany association. FetchType.Eager has the same meaning as for the other assocations. The table, which maps the association is specied with the annotation @JoinTable. This annotation must contain the name of the table. Moreover the column which holds the foreign key to the table of the class that has the associated attribute is specied with the attribute joinColumns and the the foreign key to the table of the associations target class is denoted with the attribute inverseJoinColumns. As for one-to-many association an index column for the index of the target objects in the collection can be declared with the annotation @IndexColumn. These are the most important Hibernate annotations that are used for the mapping of the eWorld classes. Few additional annotations were used, which are now explained together with the description of the concrete mapping of classes and associations to tables and columns. The class AbstractNode is stored in the table abstractnodes. As it is inherited by the classes Node and PointOfInterest, the inheritance type must be specied. AbstractNode does not have any associations to other classes. The class Connection is persisted in the table connections. The attributes fromEdge and toEdge are two many-to-one associations to the class Edge, which are stored in the columns fromedge and toedge respectively. The mapping of the class Edge is made to the table edges. This class has various associations. Its attributes fromNode and toNode are both many-toone associations to the class Node, which are saved in the columns fromnode and tonode. lanes is a one-to-many association to the class lane, which is represented by the column edge in the table lane. Moreover in the table lane there is an index column indexinedge in order to retain the order in the list. The attribute parentWay species another many-to-one association, to the class Way, and it is mapped by the column parentway. Finally, there is also a one-to-one association, to the Edge class itself, which is hold in the attribute 27

complementaryEdge. It is stored in the column complementaryedge. The class GlobalPosition is not mapped directly to a table. Its attributes can rather be embedded in the table of another class, if this class has an attribute of the type GlobalPosition. This fact is expressed with the annotation @Embeddable over the class signature. Only in the classes CircleLocation and PolygonLocation it is made use of this possibility. In the table lanes the class Lane is stored. Lane has a many-to-many association with the class Event. This association is mapped to the table event_lane, the identier of the database entry in lanes is stored in the column lane and the identier of the entry in the table events, in which the class Event is persisted, is stored in the column event. As the association is stored in a list, event_lane also has a column indexinlane, in which the index of the element in the list is stored, to maintain the correct order in the list after restoring. The class Node is stored in the table nodes. As it is inherited by the class TracLight, the inheritance persistence strategy is specied. Node has a oneto-many association to the class Connection. The foreign key to the entry in nodes is stored in the column node of the table connections. Moreover, in this table the index of each Connection entry in the list is stored in the column indexinnode. Another association is the attribute referencededges, which is a many-to-many association to the class Edge. This association is stored in the table edge_node and The foreign key to the node is stored in the column node. Also here, the index of the edges in the list is persisted with help of the column indexinnode. Besides, the class Node inherits from the class AbstractNode. Hence it has no own sequence generator, because it shares the identier with the parent class. The class PointOfInterest, which is persisted in the table pointonterests inherits from AbstractNode, too. Thus, it does not contain a sequence generator, either. It has no associations to other classes. The class TracLight, which inherits from the class Node is stored in the table traclights. It shares its identier with the parent classes Node and AbstractNode. TracLight has a complex tertiary association with the classes Edge and TracLightStateList in the attribute defaultLogic. This association is declared as follows: @OneToMany( f e t c h=FetchType .EAGER) @JoinTable ( name=" t r a f f i c l i g h t _ e d g e _ t l s l " , joinColumns = {@JoinColumn ( name=" t r a f f i c l i g h t " ) } , i n v e r s e J o i n C o l u m n s = @JoinColumn ( name=" t l s l " ) ) @MapKeyManyToMany( joinColumns = { @JoinColumn ( name=" edge " ) } ) private Map<Edge , T r a f f i c L i g h t S t a t e L i s t > d e f a u l t L o g i c ; Originally the idea was to use L i s t <T r a f f i c L i g h t S t a t e > as value type in the map. Unfortunately, it was not possible to persist such an association with Hibernate. Hence, the wrapper class TracLightStateList has to be created. The @OneToMany attribute indicates, that various TracLightStateList objects can belong to each TracLight object. This association is mapped in the table traclight_edge_tlsl. The foreign key to traclights is 28

stored in the column traclight and the foreign key to the table traclightstatelists, in which the class TracLightStateList is persisted, is stored in the column tlsl. Furthermore, the relation to the map key of the class Edge, which is a many-to-many association must be mapped to the database. This is done in the same table, in the column edge. This mapping is here declared with @MapKeyManyToMany. TracLight also has a many-to-many association to the class Way. This association in the attribute participatingWays is persisted in the table way_traclight. The corresponding entry of the TracLight object in the table traclights is stored in the column traclight, where the identier of the Way object is saved in the column way. To keep the right order in this list, the index in the list is stored in the column indexintraclight. Additionally, TracLight has a collection of simple values, in private int [ ] d u r a t i o n s ; As int is not a class in Java, there is no possibility to persist the elements of this collections just like normal objects. For instance, there is no way to assign an identier to a value of the type int. Hence the values of this association are stored in a separate table, tldurations. With Hibernate annotations this can be declared as @CollectionOfElements @JoinTable ( name=" t l d u r a t i o n s " , joinColumns = @JoinColumn ( name=" t r a f f i c l i g h t " ) ) @IndexColumn ( name=" i n d e x i n t l " , b a s e =0) @Column ( name=" d u r a t i o n " , n u l l a b l e=f a l s e ) private int [ ] d u r a t i o n s ; @CollectionOfElements species this special type of association. In @JoinTable, the name of the table is denoted as well as the name of the column for the foreign key to the TracLight objects entry in the class traclights. This column is called traclight. The values themselves are saved in the column duration, which is specied with the @Column annotation. Finally, the order in the array matters, so there is also an index column, indexintl. The class TracLightStateList, which is, as mentioned before, only a wrapper around an object of List<TracLightStateListEntry> is saved in the table traclightstatelists. It has exactly one association to the class TracLightStateListEntry, which is stored in the attribute states. Originally, this attribute was of the type List<TracLightState>. Though, TracLightState is an enumeration, and Hibernate does not support to save lists of enumerations. As a consequence, another TracLightStateListEntry was built as wrapper class around TracLightState. As this association is of the type one-to-many, in the table traclightstatelistentries, which represents the class TracLightStateListEntry, the column traclightstatelist exists, which is a foreign key to the TracLightStateList. The index of each element in the list is also persisted in the column indexinlist of the table traclightstatelistentries. The class TracLightStateListEntry, stored in the table traclightstatelistentries only contains one attribute. This is declared with @Enumerated (EnumType . STRING) private T r a f f i c L i g h t S t a t e s t a t e ; 29

As TracLightState is an enumeration, this has to be indicated manually. Furthermore, the way in that the enumeration shall be stored must be given. Here the String value of the attribute is stored. Another possibility is to store an integer, which reects the position of the value in the enumeration. The last class of the map data is the class Way. It is persisted in the table ways. Way has an association to the class Edge. This association is stored with the foreign key column parentway in the table edges, which points to the corresponding entry in the table way. The root data class for events is the class Event, which is saved in the table events. In the attribute location, a one-to-one association to the class Location exists. This association is mapped to the column location of the table events. As two classes, RoadEvent and EnvironmentEvent inherit from Event, the inheritance strategy is declared. The table environmentevents contains the entries for the class EnvironmentEvent. It inherits from Event and has hence no own identier sequence generator, as it is joined with Event by the identier when restoring. EnvironmentEvent has one special attribute, which is the attribute eventType. This is an attribute of the enumeration de.hpi.eworld.model.db.data.event.EnvironmentEvent.Type. Therefore, Hibernate must be told, that it is an enumeration. Moreover, as the attribute is called eventType and the column has the name type, the column name must be specied manually. This is done with @Column ( name=" type " ) @Enumerated (EnumType . STRING) private Type eventType ; The String value of this attribute is stored in the database. RoadEvent objects are persisted with help of the table roadevents. With type they also have an attribute of an enumeration. The enumeration here is de.hpi.eworld.model.db.data.event.RoadEvent.Type. Here also the String value is persisted. Location, which is the parent class of CircleLocation, EdgeLocation and PolygonLocation, is stored in locations. There is a many-to-many association, which is saved with help of the table location_edge. The Location foreign key is stored in the column location of this table and the Edge foreign key in edge. Here the order of the elements in the list does not matter at all, hence there is no index column in this table. The class CircleLocation is mapped to the table circlelocations. This class has two attributes of the type GlobalPosition, center and circlepoint. As GlobalPosition is not mapped to a table itself, the attributes of these two values are embedded into the table circlelocations. This is done with @Embedded @AttributeOverrides ( { @ A t t r i b u t e O v e r r i d e ( name=" l o n g i t u d e " , column = @Column ( name=" c e n t l o n g " ) ) , @ A t t r i b u t e O v e r r i d e ( name=" l a t i t u d e " , column = @Column ( name=" c e n t l a t " ) ) , @ A t t r i b u t e O v e r r i d e ( name=" a l t i t u d e " , 30

column = @Column ( name=" c e n t a l t " ) ) } ) private G l o b a l P o s i t i o n c e n t e r ; and @Embedded @AttributeOverrides ( { @ A t t r i b u t e O v e r r i d e ( name=" l o n g i t u d e " , column = @Column ( name=" c e n t l o n g " ) ) , @ A t t r i b u t e O v e r r i d e ( name=" l a t i t u d e " , column = @Column ( name=" c e n t l a t " ) ) , @ A t t r i b u t e O v e r r i d e ( name=" a l t i t u d e " , column = @Column ( name=" c e n t a l t " ) ) } ) private G l o b a l P o s i t i o n c e n t e r ; respectively. The @AttributeOverrides is necessary, as two attributes of the same type are embedded. Without @AttributeOverrides, Hibernate would try to save the values in columns that have the same name like the attributes of GlobalPosition, i.e. longitude, altitude and latitude. This would lead to a conict, if the values of both embedded attributes were stored in the same columns. The class PolygonLocation is saved in the table polygonlocations. It contains a list of GlobalPoint in the attribute points. This is a one-to-many association to an embeddable class. Hibernate supports this with @ C o l l e c t i o n O f E l e m e n t s ( f e t c h=FetchType .EAGER) @JoinTable ( name=" p o l y g o n p o i n t s " , joinColumns = @JoinColumn ( name=" p o l y g o n l o c a t i o n " ) ) @IndexColumn ( name = " i n d e x i n l o c a t i o n " , b a s e =0) private L i s t <G l o b a l P o s i t i o n > p o i n t s = new A r r a y L i s t <G l o b a l P o s i t i o n > ( ) ; @CollectionOfElements shows, that values of a type, which is not saved in a proper table, are members of this collection. Hence, an additional table must be given that holds the values. This is done with @JoinTable and the table is called polygonpoints. The foreign key to reference the right PolygonLocation is called polygonlocation. Of course, the order of the points in the polygon matters, hence the index of the elements in the list is saved in the column indexinlocation. The class EdgeLocation is rather simple. It does not have any associations to other classes. This class is saved in the table edgelocations. The associations between the dierent classes can be seen in the EntityRelationship diagram in Figure 3.5. The arrows indicate the reading direction of the names of the associations. Although most of the information is declared with Java annotations, an XML conguration is still required. This le has the lename hibernate.cfg.xml. There, it is specied that the PostgreSQL JDBC driver and the PostgreSQL dialect shall be used. Moreover, it is dened, that the created SQL statements are not printed in the standard output. Finally, it contains a list of all the classes that are mapped with Hibernate. 31

GlobalPoint 1 1

has 3..n RoadEvent 1 is 0..1 Event 0..1 has is 1 1 Location 1..n is 1 EnvironmentEvent PolygonLocation 1 is 1 is 1

has 2 CircleLocation

EdgeLocation

0..n

has

Way

0..n 1

has 1..n 1

Lane

first

has

last

has 0..1 1 0..n

0..1

1..m

TrafficLightState ListEntry 1 has

1 Connection 1

from

0..n Edge 0..1 1 complementary from 0..n to 0..n Node is 0..1 1 has 1

1..n TrafficLightStateList

0..n to

1..n

1..n

AbstractNode 0..1 is 0..1 Point of Interest

0..1

is

TrafficLight

Figure 3.5: Entity-Relationship diagram of the database model

32

Figure 3.6: Database conguration dialog

Persistence Logic There are three things, the user can do with the database plugin. Firstly he can export map and event data into a database, secondly, the user can import map and event data from a database. The third use case is derived from the other two use cases, it is to save the conguration settings of the database. The database plugin is organized in the package de.hpi.eworld.db. The DatabaseAccess object holds the database settings. If the settings, that might be restored from previous sessions are correct, the import menu entries are enabled. The settings conguration menu entry is always enabled. The export menu entry only becomes activated, when data is loaded from a source such as an OSM le, an eWorld le or a database. Finally, a progress bar, to be used by DatabaseAccess is created and some signals of that are connected. The class DatabaseAccess does the actual work, i.e. it is the only class that connects to the database. As it is a central component, it is made singleton. On its startup, it is tried to restore the database settings of previous sessions. The class also provides the means to check the database settings with the method public boolean checkSettings() Therefore with help of the Hibernate conguration le and the settings, it is intented to build a new Hibernate session and to connect to the database. If this fails, the settings are not valid. In order to change, the database settings the method the user has to click on Database conguration, which triggers the method public void configureDB() of the database plugin. An instance DatabaseCongDialog is built and the tiny conguration dialog window that can be seen in Figure 3.5.4 pops up. When the user clicks on Ok, the method public synchronized void save() of DatabaseCongDialog is called, which tries to save the settings with help of the method public void writeSettings(String url, int port, String dbname, String username, String password) in DatabaseAccess. The settings are double-checked and if they are not valid, the previous settings are saved again. Figure 3.5.4 shows the typical control ow, when the database settings are changed, including the alternatives, that the values are valid or invalid. If the user chooses Export to database from the database menu, the method 33

User

:DatabaseMenu

:DatabaseAccess

Database

Database configuration

configureDb()

<<create>>

:DatabaseConfig Dialog

Ok

writeSettings (newSettings)

checkSettings()

<<create>>

:Hibernate Session

start transaction connect alt error false writeSettings (oldSettings)

error/no response

ack

commit close

ack true

Figure 3.7: Database conguration control ow

34

public void exportToDB() of the database plugin is called. First, it is checked, whether the database is empty. If this is the case, the database schema is exported to the database. In any case, nally the map data is exported to the database. The check, whether the database is empty can be performed with the method public boolean checkSchema() of the class DatabaseAccess. It veries, if the database schema already contains tables. This has to be done with a PostgreSQL specic command. Hence the database plugin is not portable to another database system as is. However similar commands exist for other databases, such as MySQL. The method public void setSchema() exports the database schema to the database. For that, the database schema must be available as SQL statements in the le schema.sql. This le is read and parsed, and the statements are subsequently sent to the database. Meanwhile, the progress bar of database plugin is updated. The actual saving is done with the method public synchronized void save() of the class DatabaseAccess. First, possibly existing data is erased from the database, then the map data is stored in the Hibernate session, event data is saved there and nally all data of the session is commited to the database. The erasing of existing data happens in the method private void flush(). It deletes physically the data from all database tables. However, if the data in the internal database was persisted before, all the elements still have an identier number. When it is tried to store this data again, Hibernate therefore thinks, that they are already persisted. For that, all the elements in the internal database must get the identier 0. The objects are also removed from the current Hibernate session. The method private void saveMapData() saves the map data in the Hibernate session and updates the progress bar of database plugin. The same does private void saveEventData() for event data. The normal control ow of the database export can be seen in Figure A.4.4, B, B and B. The database import can be triggered by the user with the database menu entry Import from database, which calls the method public synchronized void importFromDB() of database plugin. This one basically just starts the import with the method public void load() in DatabaseAccess. The latter one just erases the internal database and the map display in the main application. Then the map and event data is loaded, stored in the internal database is displayed in the map view. Finally, the map display is activated again, which also informs other plugins about the loading of new data. The loading of map data occurs in the method private void loadMapData() and event data is loaded in the method private void loadEventData(). Permanently, a progress bar is updated to give feedback to the user. The control ow of the import is depicted in Figur B.

3.6

Simulation Visualizer
written by Nico Naumann, Matthias Kleine

Since eWorlds most common use case is to prepare and enrich map data for simulation purposes it is an obvious step forward to implement a simulation visualization. With a simulation visualization based on the open source 35

simulator sumo, it is possible to run a simulation out of eworld and visualize the results directly, without manually starting other programs. Generally this can be extended towards other simulators than sumo which is also supported by the exible plugin environment. The visualization ist currently limited to displaying vehicles and trac light states. The sumo visualizer is based on an implementation of the "Trac Control Interface" (TraCi) that is dened by SUMO and allows to connect eWorld with a sumo instance. (Note: Additional information on commands supported by the TraCi Protocol can be found in the SUMO wiki) This allows eWorld as a client to control the progress of the simulation and receive status updates using a TCP/IP-connection to the sumo instance. Since it is not desired to ask the user for starting sumo separately, the sumo startup and connection phase is integrated into the visualizer plugin. The user only has to provide information about the location of the sumo executable. The implementation of the TraCI interface as well as the visualization itself will now be described.

3.6.1

TraCI Interface

Our TraCI interface implementation separates the concrete network communication parts which are the same for any type of message (e.g. the message header is the same for any message) from the parts that are specic for certain messages (e.g. a car/node position update message contains other parameters than other messages). This separation has been implemented as follows (all package names are given relative to de.hpi.visualizer): The package simulation contains all simulation-logic related code and is split up into the packages simulation.traci and simulation.eworld. The former one contains all TraCI related code (i.e. the parts common to all TraCI commands as well as the implementation of the dierent commands) whereas the latter orchestrates the actual simulation and takes care of creating graphical items. The package simulation.traci is again split up into the packages common and commands, the former one implementing the generic network protocol and the latter one the dierent TraCI commands. Currently, only a small selection of commands and data types is implemented. In order to ease the development of further TraCI features, the implementation of the Simulation Step-command will now be explained in detail: According to the TraCI documentation, the host application sends the Simulation Step command to trigger the trac simulator to simulate the next simulation step up to target time. Furthermore it results in a Status Response command as well as a collection of Move Node commands being sent by sumo. The eWorld TraCI interface distinguishes between commands that are sent by our client and those that are sent by sumo. As can be seen in gure 3.8, the former ones are implemented using CommandGenerators and have to provide a method to create a Command object. The latter ones are implemented using CommandReaders and have to provide some form of instantiation facility that takes a Command as an input, e.g. a static method. Therefore we have to implement the Simulation Step command as a CommandGenrator and the other messages as CommandReaders. (De)-serialization of Readers/Writers to/from Command objects can make use of stream objects based on TraciInputStream or TraciOutputStream. These 36

Command +readFromStream() +writeToStream() CommandGenerator +toCommand() : Command CommandReader +fromCommand() : CommandReader

Figure 3.8: The classes used to implement TraCI commands classes extend ordinary DataIn/OutputStreams with methods to read/write TraCI datatypes, e.g. a trac light phase list.

3.6.2

Visualization of Non-ModelElements

Unlike normal ModelElements, a vehicle is not part of an eWorld le. We therefore decided to extend the existing NetworkView with the possibility to display graphics items not based on ModelElements, so called volatile model element items. As can be seen in gure 3.9, creating such an graphics item involves creating a VolatileModelElement as well as a VolatileGraphicsItem.

uses VolatileModelElement +createGraphicsItem() VolatileGraphicsItem +modelChanged()

VisualizerTrafficLight

VisualizerTrafficLightItem

Figure 3.9: Trac Light visualization implemented using volatile model elements

3.6.3

Visualization Workow

In order to start and initialize the simulation within sumo, it is neccessary to generate according network les and routes that are required by the simulation. Since there already exists a plugin that performs an export to sumo (de.hpi.eworld.export.sumo), this plugin is invoked by the visualization plugin in order to gerenate the required les. Afterwards, this information is forwarded to sumo which then loads the data. The implementation uses the extension point VisualizerProviderInterface in order to get access to the sumo exporter. After the initialization phase is nished, the status messages that are delivered by sumo are used to create a model of the current simulation state 37

Figure 3.10: The Mini Map Widget (Car.java) which is a VolatileModelElement. This model contains information about vehicles and their positions and is constantly updated while the simulation runs. Based on this model the visualization plugin displays graphical items that represent the vehicles. These items are implemented as VolatileGraphicsItems and are created from the model object. If position updates are signalized by sumo, the visualizer also updates its presentation based on the model data. Additional to the backend implementation and the graphical representation of the simulation, the user also needs an option to inuence the simulation progress. More precisely this means that the user needs to control the speed in which the simulation is running and must be able to perform a step-by-step analysis of the simulation. This is implemented via control buttons (SimulationControlToolbar) that owns the simulation control and forwards user requests to it.

3.7

Mini Map Widget

Based on lots of user request and own usage experience, we decided to introduce a new GUI element that helps the user to navigate the map in eworld. Previously, it was not possible to get an overview of the whole area that was loaded, often leading to confusion while working on the map. The Mini Map widget now shows a small overview of the currently loaded map and adds itself as a dock widget into the right dock area of eWorld. That way, it is always visible while working on the map and does not hinder the normal work with eworld.

3.7.1

Implementation

The most challenging task for the implementation of the mini map was to not inuence the performance of the navigation in eworld. As a map can consist of up to several thousand nodes and edges that are visualized, it is important to circumvent unneccessary graphical updates on the mini map. In order to accomplish this, the widget uses a pre-rendered BueredImage instead of the ViewItem that is used for the network view. This image is drawn as soon as a new map is loaded into eWorld and shown on the widget. A second challenging task while implementing the mini map was the navigation. Since we wanted the ability to navigate the main map via the mini map, it 38

is neccessary to map the coordinates from within the minimap to a visible area on the main map. Furthermore this mapping had to be done vice-versa, since the mini map has to display which map area is currently visible. This mapping from and to the main map is performed with the help of the scene coordinate system. Since both widgets, the main map and the mini map, display the same map, they are also based on the same scene coordinate system. When a user clicks on the mini map, the operating system coordinates are translated back to scene coordinates, i.e. on which location in the scene the mouse click was done. These coordinates can now be used by the main map to decide, which area shall be visible, based on this command. The same process happens backwards when the user navigates within the main map. The mini map then updates the display to show where the user currently is.

3.8

eWorld - EventServer
written by Sebastian Enderlein

3.8.1

Overview

The purpose of the eWorldEventServer is to act as a service for vehicle units (or other elements of the infrastructure) that want to access event data. The eWorld Eventserver provides them socket request channels to get informed about events that are occuring in their current area. Therefore, eWorldEventServer provides two communication interfaces: The control interface enables eWorld (or others) to trigger a data update process. Since eWorldEventServer was built to run permanently as a background service, changes to the environment made with eWorld have to be announced. The control port provides an interface to inform eWorldEventServer about these changes. Once new data is being processed in eWorld and stored in the related PostgreSQL database, eWorld sends a command to eWorld EventServer to update its cached data. The data interface as mentioned above empowers vehicle units to request information about occuring events. Although the most important events for vehicles may be those ones that occur in proximity of time and the units position, it is generally possible to access the full amount of cached data using the data interface.

3.8.2

Architecture

This section will explain the architecture of eWorld EventServer regarding communication, threading, and system architecture. Threading and scalability The design of eWorld EventServer is focused on high scalability and speed along with minimal waste of resources. All interfaces are realized using thread pools to allow concurrent access without delays. Furthermore, both - control and data listeners are running in separate threads to run independently from the core component. This enables eWorldEventServer to be highly scalable and stable even when stressed with numerous requests per second. Scalability and 39

speed are furthermore dramatically improved by the fact that all requests to eWorldEventServer in the given use cases are generally read-only, which renders all concurrent data access control via mutexes or semaphores unnecessary. The read-only access and the capabilities that arise from this will be further discussed in the section "Outlook" within this chapter. System architecture As mentioned before, the central component of eWorldEventServer is the core, that manages all listeners, downloads event data to the local cache, and provides access methods to this data.

Figure 3.11: General architecture of eWorld EventServer Figure 3.11 illustrates the architecture in an FMC block diagram. All data is retrieved using Hibernate (the same technology that eWorld uses to export data to the PostgreSQL database). Besides environment and road events, also edges and nodes have to be imported to be able to perform road-related calculations - such as the distance of a specic position to the next road. The "ServerConnection" class manages the database operations and encapsulates all Hibernate-related functionalities. The core as central element leverages the interface provided by ServerConnection to oer high-level data access methods to all threads. Figure 3.12 shows the detailed relations between all classes of eWorldEventServer. For convenience, the server core is implemented as Singleton and all worker thread are allowed to directly access the data provided, since no data manipulation happens. A special issue in this case is surely the control interface, which indeed facilitates changes to the cached data by triggering a full data refresh from the database. However, changing the environment in eWorld, which may include changing map data, would anyway result in intermixing two 40

test session and would "beam" all vehicles to random positions on the new map. Thus, it should be generally impossible to change map data during a running simulation.

Figure 3.12: Class diagram of eWorldEventServer

Communication This section describes communication-relevant elements within the architecture as well as the functionalities that are oered by eWorldEventServer in detail. As described before, data and control listener classes are permanently waiting for incoming connections. Once a client attempts to establish a connection, this request will handed over to a thread out of the pool of Data/Control Servants (the worker threads tht actually serve data). Once the servant threads are activated (and the socket connection is established) they wait for an incoming command. The type of request is dened by a command byte followed by request data. Listing 3.1 provides an overview of supported commands specied in de.hpi.eworld.util.ServerConstants inside the eWorld project. Listing 3.1: List of supported commands including byte code
public c l a s s Commands

41

{ / Command t o g e t a l l r o a d e v e n t s a t a s p e c i f i c time and on a s p e c i f i c edge / public f i n a l s t a t i c byte GET_ROADEVENTS = 0 x10 ; / Command t o g e t e v e n t s a t a s p e c i f i c p o s i t i o n and time ( s e e p r o j e c t documentation ) / public f i n a l s t a t i c byte GET_EVENTSAT = 0 x11 ; / Command t o r e t r i e v e a l l e v e n t s o f a s p e c i f i c t y p e a t a s p e c i f i c time and p o s i t i o n / public f i n a l s t a t i c byte GET_EVENTINFO = 0 x12 ; / T r i g g e r s a d a t a u p d a t e from t h e db Note : THIS C M A D CAN ONLY BE PERFORMED USING THE CONTROL PORT O M N / public f i n a l s t a t i c byte UPDATE = 0 x13 ; / Returns t h e n e a r e s t e dge t o a g i v e n ( f l o a t x , f l o a t y ) p o s i t i o n / public f i n a l s t a t i c byte GET_NEARESTEDGE = 0 x14 ; / Stop component / public f i n a l s t a t i c byte CLOSE = 0x7F ; / Unknown command / public f i n a l s t a t i c byte UNKNOWN = ( byte ) 0xFF ; }

All three GET operations are utlilized by vehicle units that want to get informaed about events. GET_ROADEVENTS only serves road-related events. The vehicle unit has to deliver start end end time (both Java int) in miliseconds to limit dene a temporal interval of interest and it also submits the current edge (Java int) it is located on. The result will be all road events within the time interval on the current edge. The complete message ow is shown in the following listing. Request: 1. byte GET_ROADEVENTS = 0x10 2. double startTime 3. double endTime 4. int edgeID 5. oat distance to start node of the edge Response: 1. byte OK = 0x00 2. int number of road events (3 to 8 x times) 3. int edgeID 4. byte event type 42

5. double start time of event 6. double end time of event 7. double distance of event to start node 8. double length of event GET_EVENTSAT delivers all environment events at a specic time and position. This position can be either absolute (x,y) or road-related (edgeID and distance to node, as shown with road events), but it is recommended to deliver absolute positions. GET_EVENTSAT requests and responses consist of the following data: Request: 1. byte GET_EVENTSAT = 0x11 2. byte positionType (position can either be absolute or on edge as above, we consider aboslute) 3. oat longitude (horizontal position) 4. oat latitude (vertical position) 5. double startTime 6. double endTime 7. oat distance to start node of the edge Response: 1. byte OK = 0x00 2. int number of events (3 to 6 x times) 3. byte event type 4. byte strength of event 5. double start time of event 6. double end time of event GET_EVENTINFO only diers from GET_EVENTSAT by allowing the requesting party to pre-dene the type of environment event of interest. The response equals completely. Request: 1. byte GET_EVENTINFO = 0x12 2. byte event type 3. byte positionType (position can either be absolute or on edge as above, we consider aboslute) 4. oat longitude (horizontal position) 43

5. oat latitude (vertical position) 6. double startTime 7. double endTime 8. oat distance to start node of the edge Reponse: see GET_EVENTSAT reponse The command GET_NEARESTEDGE delivers the closest edge to an absolute position. This function can be used to correct malicious GPS positions, for instance. To provide this functionality, the data cache of eWorldEventServer had to be enhanced. With large maps, the number of edges and nodes dramatically increases. It is not recommended to check for every edge whether the position specied is close or not, since the proximity calculation is not trivial regarding processing. Thus, performing this calculation some 100,000 times would lead to unacceptable latencies. The solution here was the introduction of the Quadtree data structure, which allows to divide data spread over a map to be incementally subdivided into quadrants. Fortunately, an open-source (LGPL) project named JTS (Java Topology Suite) developed by VividSolutions (http://www.vividsolutions.com/jts/jtshome.htm) turned out to be the perfect solution after some few adjustments (many thanks to this project at this place). By leveraging a Quadtree, a pre-elemination of far away edges was possible. The process of elimination consists of the following steps: 1. Fill the Quadtree with edges (only once after data has been cached) 2. retrieve vehicle position 3. create a larger rectangle (about 200 meters) around that position 4. lter out all edges in the qudtree that do not intersect this rectangle. The last step needs to be explained in detail. The JTS Quadtree creates rectangles around the edges (named "envelopes"). By creating recangles around the vehicle position, the proximity problem can bereduced to a simple intersection of two rectangles. The result is a list of edges that are about 100 or less meters away from the current position. The only step that has now to be taken is to nd the closest edge by calculating the distances for the edges that are left. By leveraging the Qudtree and introducing the above-mentioned algorithm, the response time for a GET_NEARESTEDGE could be reduced dramatically (the eect even increases for larger maps). The following listing briey shows the message ow during the request. Request: 1. byte GET_ROADEVENTS = 0x10 2. double startTime 3. double endTime 4. int edgeID 5. oat distance to start node of the edge 44

Response: 1. int edgeID of closest edge (-1 means no close edge found, no following data then) 2. double distance to the closest point of the edge

3.8.3

Outlook

Although eWorldEventServer is highly scalable, a large simulation using ten thousands of cars will denitely beat the system at a certain point. To enable eWorld and eWorldEventServer to even manage simulations in the size of whole counties or big cities, the following enhancement is recommended: As mentioned before, vehicle only need read access to event data, which removes makes locking and other techniques to guarantee data consitency redundant. It is possible to run eWorldEventServers in a cluster of computers. Each of these servers will once at the beginning download all event-related data and will from now on work independent from the rest of the system. It would now be necessary to reroute vehicle requests to dierent eWorldEventServers based on their stress level. This could be done by a distribution server that balances the load of requests. Small changes would also be necessary in eWorld. Instead of triggering and managing a single eWorld EventServer, the software would now have to inform the whole cluster about data updates.

3.9

eWorld - Trac Light System

3.9.1

Introduction

In this chapter a detailed description on how eWorld handles trac lights is oered. This includes how eWorld manages trac lights, generates trac light logics, how a user can edit them and how they are exported. According to the plug-in architecture used within eWorld, the component for handling trafc lights is encapsulated in an own package. Thereby it is easy to modify it independently from eWorld.

3.9.2

Data Structure of Trac Lights in eWorld

Trac Lights in eWorld are special nodes with additional attributes and methods. The main attribute is the default logic each trac light object has. This logic is computed each time an incoming edge is added to the node and holds a list of trac light states for each incoming edge. The states can be Green, Yellow or Red. At the moment those states can only be set per edge but in future versions of eWorld it is planned to enable the user to set the states per lane. 45

3.9.3

Trac Light Logic Generation

Since the data sources eWorld oers an import functionality for do not contain trac light logic information, eWorld generates a simple logic as default value. This logic can be changed by the user in the according menu. The generation algorithm uses the following information about a trac light node: Number of participating ways Default values for phase durations The rst information is necessary to decide which incoming edges can be in the state GREEN at the same time. As in the real world incoming edges that belong to the same street (way in the context of eWorld) are expected to have the same trac light logic. Depending on the number of participating ways the number of phases is dened. For each way there have to be three phases (green, yellow and red). Having dened this number the trac light logic is initialised with the state red for all phases and edges. After that the yellow and green phases are set per way. By this all edges belonging to a way have the same logic. Finally the list of trac light states for each edge is written into the default logic of the trac light node.

3.9.4

Trac Light Menu

This section should give a short introduction into the trac light menu. This menu is not only aiming at providing information about the trac light logic, the participating streets and their arrangement but also enables the user to change the trac light logic. A screenshot of the menu can be seen in gure 3.13. The user has two options to access the menu. One option is to choose "Edit All Trac Light Logics" from the Edit menu. The user can now access a list of all trac lights in the current loaded map. The second option for the user is to just right-click on a trac light in the map. This opens the context menu with the option "Edit this Trac Light Logic". This option leads to the same trac light menu but this time only the chosen trac light is shown. Nevertheless which option the user chooses he can now adjust the logic of the trac lights in the list visible in the top left part of the menu. This adjustments can be done in the logic table in the lower section of the menu. The table shown in this part of the menu represents the trac light logic. Each row thereby represents an edge whereas each column represents a phase. The cells show which state the according trac light is in for each edge in each phase. For a better user experience this is done by coloring the cells in the state colors green, red and yellow. If a user now wants to change the logic it is only necessary to select the cell that should be changed and click one of the buttons on the right to switch the state to the chosen color. By clicking "Consistency Check" in the lower right part of the menu he can automatically detect conicts in the new logic conguration, e.g. overlapping green phases of dierent edges. Furthermore the user can change the phase durations that are shown in the column headers of the table. Those numbers can be changed simply by 46

Figure 3.13: Screenshot of the eWorld Trac Light Menu changing the columns width. Therefore the user only has to move the separator between two columns in the tables header. The number changes as soon as the separator is moved and provides thereby feedback to the user on what is changed. The phase durations can also be automatically generated by using the "Auto generate logics" feature in the lower right menu. Once the user is done all changes are saved when the according button is pressed. If the changes should not be stored the user just can press Cancel at each time during the change process.

3.9.5

Export of Trac Lights

In the current version eWorld only supports the export of trac lights to SUMO. SUMO was the only trac simulation tool that was able to handle trac lights in a useful way. Furthermore SUMO is also able to generate trac light logics already taking lanes into account. Depending on the use case the user can decide to use the simple, self-modied trac light logics dened in eWorld or the in SUMO automatically generated. Nevertheless if the eWorld trac light logics should be exported, a *.tls.xml le is generated containing the information on the trac lights in the SUMO format. For further details on this format and how SUMO deals with trac lights please see the according chapter in the SUMO documentation [DK]. In the conguration le used by SUMO to load all necessary information the generated *.tls.xml le has to be added in the tag "additional-les". Once this cong le is loaded by SUMO, the information is retrieved from all the named les and the simulation can be started. The trac lights in this simulation behave as dened in the trac light menu in eWorld. For further details on the export process please see the according chapter 3.10. 47

3.10

eWorld - Export to SUMO

3.10.1

Introduction

In the following chapter the SUMO export functionality of eWorld is presented. Details are oered on what information and in what format SUMO can process, how eWorld generates this data and what needs to be taken into consideration in order to prevent errors. Furthermore it is explained what options the user has during the export process. Figure 3.14 shows the SUMO export menu of eWorld.

Figure 3.14: Screenshot of the eWorld menu for the SUMO export

3.10.2

Export of map data

SUMO needs three les in order to visualize a map. Those les are: *.edg.xml - An XML-File containing information on all edges in the map *.nod.xml - An XML-File containing information on all nodes in the map *.net.xml - An XML-File containing aggregated and enriched information about the map 48

The rst le describes all the edges in the map. This data includes start and end node, an id and the number of lanes the edge has. Furthermore the maximum velocity is stored as well as the priority. The value table for those values has been specied within eWorld. Depending on the priority dened the input data (mainly OSM les) those values are set. For further details on the OSM priorities please see the according chapter. The second le holds all information on the nodes in a map. This includes the coordinates of the point, an id and the type. The latter one is only set if a special type such as TracLight occurs. In this case there are additional exports necessary that are described in the Export of trac lights section. The last le is generated by a tool named netconvert that is oered by SUMO. In the export menu the user has the option to call this program automatically. By providing the information where the program is located and which arguments should be passed, eWorld will call the program and thereby automatically generate the .net.xml le. For further information on the netconvert arguments please see the according SUMO documentation. Additionally to the before mentioned les eWorld also generates a .poi.xml le that contains information on all the points of interest shown in the map. This le can not be processed by SUMO but may be useful for other applications that want to use this data.

3.10.3

Export of trac lights

Since the data format for SUMO trac lights is not very intuitive the export is not as well. Just to provide a quick intro to the SUMO trac light logic data format the following code snippet shows the XML denition of an example trac light. <tl-logic type="static"> <key>3570b0</key> <subkey>1</subkey> <phaseno>6</phaseno> <offset>0</offset> <phase duration="20" phase="1100" brake="0011" yellow="0000" /> <phase duration="4" phase="0000" brake="1111" yellow="1100" /> <phase duration="6" phase="0000" brake="1111" yellow="0000" /> <phase duration="20" phase="0011" brake="1100" yellow="0000" /> <phase duration="4" phase="0000" brake="1111" yellow="0011" /> <phase duration="6" phase="0000" brake="1111" yellow="0000" /> </tl-logic> The following list provides details on the tags used in this XML le: tl-logic: denes the begin of the description of a tls-logic type denes the tls-algorithm used (static|actuated|agentbased) key: the node id subkey: used to separate dierent programs for the same junction phaseno: the number of phases 49

 oset: the oset by which the tls shall change to next phase phase: denition of a phase Especially the last item is kind of tricky. A phase is described by its duration and the bit sets that represents the streams of trac. Each number in a bit set thereby represents one lane of a junction. In the simple example given above there are four lanes distributed on two edges. Which state the trac light has is encoded in the bit sets. To decide what trac light state a lane has one has to take all three bit streams into account. For example in the rst phase, the rst lane has the values 1 (phase), 0 (brake) and 0 (yellow). This represents the state GREEN. A full description can be found in following table. Phase 1 0 0 Brake 0 1 1 Yellow 0 1 0

Green Yellow Red

Table 3.2: SUMO trac light states There is one more valid state which is 1 (phase), 1(brake) and 0 (yellow). This state represents a green trac light state but the vehicles still have to brake since there may be other green trac lights. In this case the vehicle on a lower priority road has to wait. Since this information is not accessible from OSM data imports and for simplication reasons this state is disregarded. The other states are generated by serialising the trac light states dened in eWorld. The result is a *.tls.xml containing the dened trac light logics in the SUMO format. For a convenient handling of trac lights, eWorld oers a graphical interface to modify trac light logics. Further information on this topic can be found in the according chapter 3.9. For a more detailed description on trac lights within the SUMO application please refer to the SUMO Trac Light documentation4 .

3.10.4

Export of events

One main functionality of eWorld is the support of events. At the moment there are environment events (ice, rain, fog, and snow) and road events (road work and accident). Those events have no real counterpart in SUMO. Therefore eWorld uses constructs of SUMO to simulate events. Those two constructs used at the moment are variable speed signs (VSS) and rerouter objects (see http://sumo.sourceforge.net/docs/gen/user_chp06.shtml). With the help of the rst the speed limit on an edge can be adjusted dynamically. If the event ice occurs on a special edge, the speed limit can be reduced to a half for the event duration. How much an event inuences the speed limit is now dened within eWorld but will be congurable in a future version of eWorld. At the moment the following factors are eective. If multiple events occur on the same edge the factors are multiplied. For example, if it rains on a street where there are also road works going on the speed limit is reduced to a quarter of its original value.
4 http://sumo.sourceforge.net/docs/gen/sumo_moreon_tls.shtml

50

Event ICE FOG SNOW RAIN ROADWORK

Factor 0.5 0.7 0.8 0.5 0.5

Table 3.3: eWorld event eects For each edge that events occur on there will be one VSS denition le (vss_<EDGE_ID>.def.xml). In this le all the changes of the speed limit are dened used the structure shown in the code section below. <vss> <step time="<TIME>" speed="<SPEED>"/> </vss> For accident events the second construct is used, the so called rerouter object. This object is used by SUMO to change the route of vehicles that would normally pass the aected edge. The structure of such an object is shown below. <rerouter> <interval begin="<BEGIN_TIME>" end="<END_TIME>"/> <closing_reroute id="<EDGE_ID>"/> </interval> </rerouter> At the moment eWorld only uses the closing_reroute action. For information on this and other actions please see the according SUMO documentation. If the user decides to simulate an accident in eWorld an rerouter denition le is created for each edge aected (rerouter_<EDGE_ID>.def.xml). A nal event le provides information about all the several denition les (*.evt.xml). In case of VSS denitions there is only one le per edge but one trigger for each lane. The references are set in the trigger tag within an event le. <trigger id="<ID>" objecttype="lane" objectid="<LANE_ID>" attr="speed" file="vss_<EDGE_ID>.def.xml" /> For rerouter objects the trigger tag looks a little bit dierent. The object type is REROUTER and instead of an ATTR attribute the probability is dened. This attribute species how many vehicles should be rerouted (between 0 (none) and 1 (all)). <trigger id="<ID>" objecttype="rerouter" objectid="<EDGE_ID>" file="rerouter_<EDGE_ID>.def.xml" probability="1" />

3.10.5

Export of simulation data

Besides those les for visualization, trac light logic and event denitions eWorld can also trigger the generation of a SUMO route le (*.rou.xml) which 51

is essential for a meaningful trac simulation. A route, in terms of sumo is a consecutive list of edges that can be driven by vehicles. The route denition le contains the specication of all routes that are available for vehicles during the simulation, as well as information on when a vehicle shall be emitted onto the route. eWorld provides two options to generate such a route le: 1. Generate random routes using duarouter The tool duarouter that is shipped with SUMO allows to generate random routes and vehicles given a *.net.xml le. That way, the simulation is lled with vehicles driving arbitrary pathes through the map. In order to enable this option, you need to specify the path to the duarouter executable and optionally provide additional parameters for the generation. 2. Using custom routes Using this option, the *.rou.xml will be created by eWorld based on the users route denitions. duarouter will not be used since the routes are not generated. Please note that automatic route generation using duarouter is only available if a .net.xml le is generated as well. This le is essential to the duarouter application since it holds all information on how the map looks like.

3.10.6

Export of dump conguration

If one wants to analyse the outcome of trac simulations, it is necessary to collect data during the simulation. SUMO provides dierent techniques for this and we make use of one of them, the aggregated edge/lane dumps. There you specify one or more interval lengths, the type of dump (edge or lane) and the lename. During the simulation SUMO will collect dierent types of data and aggregate them over the specied interval(s). Note that since SUMO version 0.10.0 the conguration of dump les needs to be in a separate le with the ending *.add.xml. The format of the conguration also changed. For that reason we implemented a function, which determines whether the local SUMO version is greater than a speciable version number. We use this function to vary the export behaviour depending on the local SUMO version.

3.10.7

Summary

To sum it up, the following les are created during a SUMO export process: *.edg.xml - edge descriptions *.nod.xml - node descriptions *.tls.xml - trac light system descriptions *.evt.xml - event denitions vss_*.def.xml - variable speed sign denitions rerouter_*.def.xml - rerouter denitions 52

 *.net.xml - SUMO net le *.rou.xml - route descriptions *.add.xml - additional descriptions, used for dump conguration (for SUMO version > 0.10.0) *.sumo.cfg - conguration le As mentioned before the *.net.xml and the *.rou.xml are generated optionally depending on the user. Finally eWorld creates a *.sumo.cfg le that is needed by SUMO to import a simulation into GUISIM, the graphical user interface to the SUMO application. Once the user has exported the data from eWorld to SUMO he is instantly able to load and run the simulation in SUMO.

3.11

Car Editor
written by Florian Thomas, Lutz Gericke

When importing SUMO routes, there are also so called vehicle types, that are imported. Before, eWorld only knew a default vehicle type. Types that were dened in route les were simply ignored. Now you can edit these imported vehicle types and even add other user-dened types, that you can apply to routes, trips and scenarios. The terms vehicle type and vehicle respectively car type and car was a little confusing in eWorld before. Vehicle sometimes meant vehicle type. By now, every usage in the eWorld UI should be unied. So vehicle type or car type means the concept or class of objects and car or vehicle means the concrete instance of this class. A Vehicle Type is a Tuple of id, acceleration, decaleration, length, maxspeed and color. Until now only one DefaultVehicle-Type existed with values of 0.8=accel, 4.5=decl, 3=length,7=maxspeed. These values are unrealistic and denitely falsify the results of the simulation, as for example maxspeed 7 means 7m/s or around 25 km/h and an acceleration of 0.8 m/s2 is even slower than a S-Bahn5 . There is also another parameter called Sigma. The only description of this property is The driver imperfection 6 and in every example it is set to 0.5. So we decided to leave this out as an option for the user and use this default value for all cars. The car editor gives the possibility to edit the behaviour of all cars of a vehicle type to appropriate values. You can now add, edit, remove vehicle types, which are saved in a global conguration storage (Settings) provided by the Core Plugin. Settings is an abstraction layer for saving application specic information. It uses Java Properties les to save its attribute-value pairs. The ability to add car types generated new problems in the trip and route conguration. So far there was no consistent solution to apply manual dened car types to routes or trips. This UIs showed obviously some room for improvement in the area of usability. These usability issues concerning vehicle types were cleaned up. You can now choose a certain vehicle type for a trip and also
5 http://de.wikipedia.org/wiki/Beschleunigung 6 http://sumo.sourceforge.net/docs/gen/sumo_user.shtml#user_chp05-own_routes

53

for the single vehicles added to a route. Another task was to extract the editing functionality out of the SUMO Exporter Plugin into a new one. Before, all information concerning vehicles was stored together with SUMO-specic export functionality. This could have lead to problems when possibly adding other trac simulators the eWorld, that are also aware of vehicle types.

Figure 3.15: Car Editor Dialogs

3.12

Importer

EWorld provides dierent capabilities to import a network of roads of dierent sources and formats. Therefore eWorld provides three types of importers as plug-ins, which are described in the next sections.

3.12.1

Organisation of Importer Plug-Ins

All of the three importer plug-ins have dierent functionality in common, which is the motivation of introducing a package de.hpi.eworld.importer for common importer functionality. It consits of common plug-in functionality and the parser for OSM7 XML les to avoid redundant implementations of it. As shown in gure 3.16 the importers for OSM data and also the importer for SUMO data imports this package.
7 OSM

is the short form of OpenStreetMap: www.openstreetmap.org

54

<<import>>

de.hpi.eworld.importer <<import>>

<<import>>

de.hpi.eworld.importer.le

de.hpi.eworld.importer.osm

de.hpi.eworld.importer.sumo

Figure 3.16: Organisation of Importer Packages

Data import Each of the three importers follow the same functional principle. The user provides via a plug-in specic GUI the source of the import and starts the import by a click on a button. Triggered by the click on the button a progress dialog is displayed and the import is started. The import itself is executed in a plug-in specic thread, which is an instance of the Java class Observable and implements the Java interface Runnable. The Observer of this instance is the plug-in specic dialog, which sets the current progress via a setter method of the progress bar dialog. As you can see in gure 3.17 the importer plug-ins make usage of the well known observer pattern. Therefore each specic import dialog registers itself as observer to the specic import thread. If something goes work during the import process the specic plug-in is notied, which displays an error dialog as reaction.

<<interface>> Observer

* JDialog

Observable

<<interface>> Runnable

OsmThread

OsmWebImportDialog 1 1

OsmFileImportDialog 1 1

ProgressDialog

Figure 3.17: Examplary overview of OSM importer classes

55

3.12.2

OSM Importer
written by Thomas Beyhl

There are two types of OSM importers in eWorld. The rst import plug-in parses an OSM XML le, which is placed on the local hard disk drive, and is called OSM File Importer. The second plug-in loads OSM data from an OSM server and parses the returned XML content. Therefore it is called OSM Web Importer. Both plug-ins have in common, that they need to parse OSM XML content and therefore used the OSM XML parser contained in the package de.hpi.eworld.importer. The OsmThread decides by the given parameters which import strategy it has to use and lls the model according to the parsed content.

3.12.3

SUMO Importer
written by Thomas Beyhl, Florian Thomas, Lutz Gericke

The motivation for the development of this Plugin was a concrete request out of the scientic community to import SUMO network denitions. So there are several free projects using the SUMO .net.xml le format to provide free maps. These projects have also predened route denition les (.rou.xml) in SUMO format that replay real world scenarios, like the morning time rushhour. There are also ambitions to represent real world trac light phases in these maps to become even more realistic. One of these projects is TAPAS cologne8 .

Figure 3.18: SUMO Import Dialog

Network denition analysis Supported by a GUI (Figure 3.18), the user chooses the .net.xml-File. This is mandatory for the import process. Furthermore the user can specify whether to import including trac lights from the .net.xml le or if routes from an second le should be imported. Routes cannot be imported without giving a network denition because the edge-IDs are unique for a pair of route-network denition. The netle import is realized by extending the ImportProvider extension point of the de.hpi.eworld.importer plugin. Currently there is a DOM parser used for importing the XML-content, because it was too complex parsing especially the trac light denitions using a SAX parser, as it has been done in
8 http://sumo.sourceforge.net/downloads/add_data.shtml

56

the rst experiments. An important fact that still leads to display problems is the translation between the 2 coordinate systems used by eWorld and SUMO. In eWorldLib there was already a library existing for these calculations, but I had to do small changes that should enhance the accuracy of these translations. Nevertheless, applying multiple projection calculation costs accuracy and leads in some cases to frayed ways.

3.13

Trac Light logic extraction

The trac lights cost most of the importers development time. The trac light logic is not documented very well. To give an example of a trac light detion, here is a short .net.xml le extract dening a trac light logic (Figure 3.19).
<t l l o g i c t y p e=" s t a t i c "> <key >870 e 2 f </key> <subkey >1</subkey> <phaseno >9</phaseno> < o f f s e t >0</ o f f s e t > <p h a s e d u r a t i o n ="20" p h a s e ="000000111" b r a k e ="111111000" y e l l o w ="000000000" /> <p h a s e d u r a t i o n ="4" p h a s e ="000000000" b r a k e ="111111111" y e l l o w ="000000111" /> <p h a s e d u r a t i o n ="6" p h a s e ="000000000" b r a k e ="111111111" y e l l o w ="000000000" /> <p h a s e d u r a t i o n ="20" p h a s e ="111000000" b r a k e ="000111111" y e l l o w ="000000000" /> <p h a s e d u r a t i o n ="4" p h a s e ="000000000" b r a k e ="111111111" y e l l o w ="111000000" /> <p h a s e d u r a t i o n ="6" p h a s e ="000000000" b r a k e ="111111111" y e l l o w ="000000000" /> <p h a s e d u r a t i o n ="20" p h a s e ="000111000" b r a k e ="111000111" y e l l o w ="000000000" /> <p h a s e d u r a t i o n ="4" p h a s e ="000000000" b r a k e ="111111111" y e l l o w ="000111000" /> <p h a s e d u r a t i o n ="6" p h a s e ="000000000" b r a k e ="111111111" y e l l o w ="000000000" /> </ t l l o g i c >

Figure 3.19: Sample SUMO trac light logic The TL-Logic uses bitmasks, that dene which street has which sign in which phase. By the length of the bitmask you can conclude, how many edges are involved in the trac light logic. Then you need to assign the corresponding bits of each phase, brake and yellow attribute to a specic edge. Because there is no order between the edges given, sometimes this leads to unexpected results. The main problem is a dierence of eWorld and SUMO handling trac ows. SUMO connects lanes to other lanes on other edges at junctions, but eWorld only connects whole edges at junctions. That is why the trac light import is marked as experimental at the moment, because the results can dier from what is expected. If we want to support all SUMO trac light features, we should implement the lane-model for trac lights. In one of our weekly meetings, we decided to declare a rework of the complete trac light system as a future task.

3.13.1

Route File import

Importing the .rou.xml le is basically a simple task, but grows in complexity when you look at the car denitions. The route denition itself is a string containing the IDs of edges seperated by spaces. One big problem was it to bridge the gap to the exporter.sumo Plugin which holds all Route denitions to add the imported routes. Before, all route and trip information was stored in the exporter.sumo Plugin. Then there were 2 Plugins that are separated by their tasks. The existing exporter.sumo Plugin was only responsible for 57

<r o u t e s > <v t y p e i d ="SUMO_DEFAULT_TYPE" a c c e l ="0.8" d e c e l ="4.5" sigma ="0.5" l e n g t h ="5" maxspeed="70"/> <r o u t e i d =" h o r i z o n t a l " m u l t i _ r e f ="x">2 f i 2 s i 1 o 1 f i 1 s i 2 o 2 f i </r o u t e > <r o u t e i d =" v e r t i c a l " m u l t i _ r e f ="x">3 f i 3 s i 4 o 4 f i 4 s i 3 o 3 f i </r o u t e > < v e h i c l e i d =" v e r t i c a l 1 " t y p e="SUMO_DEFAULT_TYPE" r o u t e =" v e r t i c a l " d e p a r t ="10" p e r i o d ="1" r e p n o ="30"/> < v e h i c l e i d =" h o r i z o n t a l 1 " t y p e="SUMO_DEFAULT_TYPE" r o u t e =" h o r i z o n t a l " d e p a r t ="10" p e r i o d ="1" r e p n o ="30"/> </ r o u t e s >

Figure 3.20: simple SUMO .rou.xml le Export to SUMO and a new editor.routesandtrips Plugin dealed with all data storage concerning routes and trips including the Route and Trip Editor UI. The separation of duties claried many things for the further development. In the .rou.xml-Files (example in Figure 3.20) coming out of SUMO you get only Random cars. Because there was a car editor planned, the extraction of the car denitions paused until we really had multiple car types in the export les and not only random cars. The import of the vehicle types belonging to the routes is now implemented in the SUMO importer. It is an optional import task that the user can choose if it is reasonable. The import process uses 3 steps: import of route denition strings, import of vehicle types and creating concrete vehicle instances from vehicle types and assigning them to given routes. The import of route les had to be adjusted for use with the new SUMO format (SUMO version >= 0.9.10). Due to the lack of maintenance, the development of the editor.routesandtrips Plugin has been stopped. Thus, it is likely, that it does not work properly but it may be reactivated, if it is really needed in the future. The import of SUMO .rou.xml ules is still possible.

3.14

Scenarios
written by Gerald Tpper

The motivation of a relization of such a plugin was the idea to oer a simple way for the creation of special trac situations (scenarios). A scenario could be an event (e.g. football game, concert), which causes massive trac in direction to the event location.

3.14.1

Implementation

First of all appropriate existing super classes had to be found for the view (AreaItem), which can be dragged from the scenarios dock widget and can be dropped on the map, and the model (Area), which holds all attributes of an area. As gure 3.21 shows the AreaItem is an extension of an AnnotationItem and the Area is an extension of a ModelElement. As a concrete shape a CircleAreaItem is implemented. Other shapes could be implemented by deriving from AreaItem. An Area consists of the following attributes (most of them are only relevant for start areas): 58

Figure 3.21: AreaItem and Area are derivations of existing classes areaType - a value which represents whether this area is a start or destination area; a value of the enumeration AreaType (START or DESTINATION) location - an instance of the class Location; in case of a CircleAreaItem it is a CircleLocation identier - a string which represents the identier of this area simulationTime - a value which species the simulation time when the vehicles should be emitted in this start area vehicleCount - a value which represents the number of vehicles that should be emitted in this start area vehicleEmitInterval - a value which represents the time interval between two emitted vehicles vehicleTypes - a list of vehicle types which should be emitted in this start area destinationAreas - a list of destination areas which should be a destination for this start area After the denition of a scenario in eWorld it can be exported to SUMO and visualized on the map. During the export a xml-le will be build which contains trip denitions and incorporates all parameters of the dened areas. There exist two special cases as well: the user species either no start area or no destination area. If no destination area is dened, the vehicles will end up on a random edge on the map. If no start area is dened, the vehicles will be emitted on a random edge on the map. Needless to say that all parameters have to be dened in the destination areas. Particularly the attribute simulationTime represents the time when the vehicles should end up in this destination area. Consequently the approximate start time of each vehicle is computed automatically.

3.15

Simulation Statistics
written by Philipp Maschke

This plugin covers the managment of statistical data from simulation runs and their visualization in dierent ways. 59

It mainly uses the SUMO framework as its source for statistical simulation data in the form of aggregated edge/lane dumps. The implementation of this feature is roughly separated into three parts: (1)Creation & Import of simulation data, (2)Management of the data within eWorld and (3)Visualization of simulation data.

3.15.1

Collecting and importing simulation data

At rst, we examined dierent types of statistical data concerning how useful they would be and how they could be collected using SUMO. One option was to use so-called network state dumps, which store information about all vehicles on all streets for every simulation step. We quickly dropped this option, because this would create extremely huge les with only basic information. The second option are aggregated lane/edge dumps, which provide information about dierent measures (mean speed, density, number of stops, ...) for all streets. However, this information is aggregated over user-dened intervals of simulation steps, so the granularity of the data and thus the size of the dump les is congurable. If multiple intervals are dened, the data for each is stored in a separate le. We chose this option, because it already gave all the measures we needed, provided some useful options and seemed quite straight-forward to implement. The export to SUMO has been modied to trigger the creation of these dump les. For more information see section 3.10. To import these les into eWorld, the importer.sumodump plugin was added. It provides methods that take a lename as input and import the contained data into an internal data model (see next section). The actual import process itself is quite similar to the import of OSM les, just that the formats are dierent. There is also a method, which nds all dump les of a simulation run by parsing the SUMO conguration le of that simulation. These les can then be imported with the above process. As mentioned above, these features and corresponding classes were added as a separate plugin in the beginning. Some unexplainable classpath and JavaPlugin-Framework problems forced the whole plugin to be merged with the simulationstatistic plugin. We still have tried to keep the coupling of the importer and the statistics classes as weak as possible, so that they may be separated without much eort in the future.

3.15.2

Managing statistical data in eWorld

The data model for statistics Because this feature is completely new in eWorld, there was no appropriate data model to represent the statistical data. Figure 3.22 shows the class structure that was created to represent statistical data within eWorld. The data model was designed to be as independent from the SUMO data structure as was practical. On the one hand, it should be independent, because SUMO may not be the only simulator eWorld should support. On the other hand, it would make no sense to spend a great deal of time trying to anticipate requirements, that future simulators may have for the data model. Especially considering that currently, SUMO is eectively the only one that is supported. 60

StatisticsDataManager enumeration ValueType +SAMPLEDSECONDS +TRAVELTIME +DENSITY +OCCUPANCY +SPEED +NRSTOPS +VEHICLESENTERED +VEHICLESLEFT +VEHICLESEMITTED +MAXSPEED +MINSPEED +ROADPRIORITY +text() : string +measurementUnit() : string +description() : string

-datasets *

0..1 StatDataset

+getDataFile() +belongsToCurrentMap() : bool +hasLaneData() : bool +isAutomaticImport() : bool +getName() : string 0..1 -intervals * StatInterval

AbstractStatLine +getBegin() +getEnd() +getMeanValue(in type : ValueType) +getValue(in type : ValueType)

StatEdge * 0..1 -edges +computeLaneMeans()

-lanes

StatLane

0..1 *

Figure 3.22: Data model for statistical data

61

Apart from the independency criterion, the data model was enlarged in a few places to store some attributes of the underlying street network, which the simulation is based on. That way, consumers of the data model (primarily the data visualizers) can display additional information to the user without any further eort. Such information, for example maximum and minimum speed limits, street names or road types, could prove to be very valuable for the user to better interpret the statistics. Admittedly, this creates some redundancies, because such information are stored once in the internal network model and once in the statistical data set. But the advantages should outweight this rather insignicant disadvantage. Organizing the data sets The plugin can keep multiple sets of statistical data at once, which area all handled by the SimulationStatisticManager class. It is implemented as a singleton, like the manager for map elements. The manager for simulation data is used by the sumodump import plugin, to add new data sets, and also by all consumers of statistical data, to access the dierent data sets. The manager also implements the functionality for looking up some attributes of the underlying street network (if there is one) and adding them to the data set, as was explained in the previous section.

3.15.3

Visualizing statistical data

There are dierent ways to use the simulation data, once it is stored in eWorld. Showing the raw data The most basic option is to view the original le, where the data was imported from. For this purpose, the Java Desktop class is used to retrieve the local systems browser. Generic chart generation
written by Lutz Gericke and Philipp Maschke

The classical way to visualize statistical data is showing charts. To still be able to use an existing toolkit and not having to write one ourselves, we chose to use the JFreeChart toolkit, which is Java/Swing based, and display each chart in its own window. The conguration of the charts is still located within the eWorld interface. There was some discussion as to which kind of charts we should provide to the user. On the one hand, we want to provide many dierent kinds of charts with a lot of options, so the user can choose exactly what he wants. On the other hand, we should limit the user interface in such a way, that it does not overwhelm the user and is still comprehensible. We decided to go for a compromise by limiting the variety of types of charts, but making these fully congurable. Based on the infrastructure to import SUMO-Dump les, a user interface (Figure 3.23) has been developed, which allows it to simply generate graphs 62

based on the Edge Statistics. Two kinds of charts are dierentiated: dependency charts, where you can see if a parameter is depending on a specic other one e.g. the number of stops will be potentially higher if the tracs density is growing. The data is drawn onto the chart window as a scatter plot, so every value-combination of the input series data becomes a data point. The second kind of chart is the interval timeline chart. The user can see dierent parameters developing during the simulation process. Here you can specify multiple parameters, that will be plotted as lines into the chart window. Chart windows are not modal, so you can generate multiple charts to evaluate them manually by compare dierent scenario congurations. The GUI for choosing parameters for the charts, that are used in the charts is completely free. You can choose every combination of every possible parameter. This generic approach gives the possibility to instantly use new parameters for the charts without any further changes to the code. The chart generation is a good starting point for comparing theoretical models of parameters in trac simulations with concrete values derived from experiments and practical simulations. A good example is, how speed and density depend on each other under dierent conditions. There are already existing theoretical models, such as Greenshields model of the speed-density-relation9 which can now be conrmed practically by simulating them.

Figure 3.23: Chart Generation GUI and sample graphs

9 Greenshield published his theory in 1934/35. These simple model is not fully usable for multi-lane streets such as highways.

63

Visualization on the map We also provided the funtionality for visualizing statistical data on the network map. This creates a direct and intuitive mapping from statistical values to the streets they belong to. Of course, this only works for datasets, that belong to the current network map. The data can be visualized by means of two dierent techniques, which are coloring and the manipulation of line widths. The latter is especially usefull in bigger maps to reduce complexity by hiding unimportant streets. The implementation of this feature proved to be a bit more challenging than excpected. The reason is that the whole rendering algorithm was changed during the last semester, for performance reasons. Since then, consecutive rows of edges (together with their lanes) are represented by Way objects. These objects are also responsible for rendering their edges and lanes. Previously, each model element had a corresponding ViewItem, which satised the ModelView-Controller paradigm. Now however, the ViewItems for edges and lanes were either discarded or subsequently ignored. The main problem with implementing the data visualization was to somehow transport the color and line width informations from the model elements (edges and lanes) to the way object responsible for rendering them. And to do so in such a way, that the information is displayed in the correct places. One solution of this problem would have been to bypass it completely, by adding new view items for each model element, which would then be drawn above the existing way items when visualizing data. However, this would cause a major performance loss and thus nullify the positive eects of the previous changes. We solved this problem by adding the needed attributes directly to the underlying model elements (in this case, the inidividual lane objects), which are manipulated by the simulation statistic plugin. A change of these attributes then causes a dierent rendering on the map display. The disadvantage of this approach is, that the conceptual object Lane is used to implement application specic funtionality, which violates the modelview concept. On the other hand, though, we avoid having to create new display objects for each lane or edge, which would cause major performance problems on bigger maps. Conceptually it would also be possible to recreate the lanes view objects and use these during the rendering. The current implementation did not allow this approach, though, and the time did not suce to do a complete makeover.

64

List of Figures
2.1 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 3.13 3.14 3.15 3.16 3.17 3.18 3.19 3.20 3.21 3.22 3.23 Software Simulation Environment (FMC Block Diagram) . . . . NetworkView in context of the Scenario framework . . . . . Road network model for GUI . . . . . . . . . . . . . . . . . Event model for GUI . . . . . . . . . . . . . . . . . . . . . . Conguration of the Projects Build Path . . . . . . . . . . . Entity-Relationship diagram of the database model . . . . . Database conguration dialog . . . . . . . . . . . . . . . . . Database conguration control ow . . . . . . . . . . . . . . The classes used to implement TraCI commands . . . . . . Trac Light visualization implemented using volatile model ments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Mini Map Widget . . . . . . . . . . . . . . . . . . . . . General architecture of eWorld EventServer . . . . . . . . . Class diagram of eWorldEventServer . . . . . . . . . . . . . Screenshot of the eWorld Trac Light Menu . . . . . . . . Screenshot of the eWorld menu for the SUMO export . . . Car Editor Dialogs . . . . . . . . . . . . . . . . . . . . . . . Organisation of Importer Packages . . . . . . . . . . . . . . Examplary overview of OSM importer classes . . . . . . . . SUMO Import Dialog . . . . . . . . . . . . . . . . . . . . . Sample SUMO trac light logic . . . . . . . . . . . . . . . . simple SUMO .rou.xml le . . . . . . . . . . . . . . . . . . . AreaItem and Area are derivations of existing classes . . . . Data model for statistical data . . . . . . . . . . . . . . . . Chart Generation GUI and sample graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ele. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 15 16 17 20 32 33 34 37 37 38 40 41 47 48 54 55 55 56 57 58 59 61 63 81 83 84 85 86

A.1 General dabase export control ow . . . . . . . . . . . . . . . . . B.1 B.2 B.3 B.4 Database import control ow . . Check, if the database is empty . Control ow for the setting of the Database saving control ow . . . . . . . . . . . . schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

65

66

List of Tables
3.1 3.2 3.3 A.1 A.2 A.3 A.4 DUAROUTER/JTRROUTER random generation arguments . . SUMO trac light states . . . . . . . . . . . . . . . . . . . . . . eWorld event eects . . . . . . . . . . . . . . . . . . . . . . . . . TIGER record types Nodes-le elements . Edge attributes . . . Type attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 50 51 75 79 80 80

67

Bibliography
[DK] Institut fr Verkehrsfhrung und Fahrzeugsteuerung D. Krajzewicz, Deutsches Zentrum fr Luft-und Raumfahrt e.V. Simulation of urban mobility. http://sumo.sourceforge.net/.

[Dou] Douglas-peucker-algorithmus wikipedia. http://de.wikipedia.org/wiki/Douglas-Peucker-Algorithmus. [emf] Eclipse modeling framework http://www.eclipse.org/modeling/emf/. Freie project vektor-geodaten (emf). osnabrck.

[Gmb] Intevation GmbH. Frida: http://frida.intevation.org/.

[Groa] OpenStreetMap Group. Openstreetmap protocol version 0.5. http://wiki.openstreetmap.org/index.php/OSM_Protocol_Version_0.5. [Grob] OpenStreetMap Group. http://www.openstreetmap.org/. [HF] [hib] [Ins] Openstreetmap.org.

Jrme Hrri and Marco Fiore. Vanetmobisim 1.1 user manual. http://vanet.eurecom.fr/VanetMobiSim_1_0__Manual.pdf. Hibernate. http://www.hibernate.org/. Environmental Systems Research Institute. Esri shapele technical description. http://www.esri.com/library/whitepapers/pdfs/shapele.pdf. F. Ramm I. Scholz. Java http://josm.openstreetmap.de/. open street map editor. jet).

[IS] [jet] [jpf] [otC]

Jet tutorial part 1 (introduction to http://www.eclipse.org/articles/Article-JET/jet_tutorial1.html. Java plugin framework (jpf) - home. http://jpf.sourceforge.net/.

U.S. Bureau of the Census. Census 2000 tiger/line data. http://www.esri.com/data/download/census2000_tigerline/index.html.

[RES] REST. Rest. http://www.re.st/. [Sce] Scenario: Scene https://scenegraph.dev.java.net/. 68 graph implementation.

[Sun]

Sun. Jfc/swing. http://java.sun.com/javase/technologies/desktop/.

[Une] Unesco. Oceanteacher formats example les. http://ioc.unesco.org/Oceanteacher/OceanTeacher2/07_Examples/examples.htm. [War] Frank Warmerdam. Shapele c library. http://shapelib.maptools.org/.

69

Appendix A

Data Sources and Formats

A.1.1

Overview

OpenStreetMap.org is a mapping service, which allows everybody to view, edit and use geographical data in a collaborative way from anywhere[Grob]. This community based approach looks promising as people populate and check OSMs database frequently. Besides serving requests for a certain area, OSM makes all of its data available in a le called planet.osm, which contains each and every detail currently available on OSM. Since planet.osm les are archived and hosted by dierent providers, you can see the growth of data. In October 2006, the planet.osm database was 3GB. Only one year later, the database was populated with over 11GB of information. With regard to our aims, only data available for bigger cities in Germany is relevant for now. OSM provides fairly detailed material for areas, such as Berlin, Frankfurt, or Munich. In addition, projects like FRIDA[Gmb] integrated their streetmap datasets into the OSM database thus contributed a large amount for areas around cities such as Cologne or Osnabrck. As of the beginning of October 2007, 0.5 is the current version of the OSM protocol, which supports versioned data.

A.1.2

Advantages and Disadvantages

The advantages of OSM are rather obvious as the entire content is free to use for everybody. Thus we can use street and point of interest data without having to care about legal restrictions. In addition, the OSM system allows precise requests of features, e.g. features in a specied area, only features with certain attributes, and features related to a given feature. An example for the latter is to retrieve all streets that cross a given point. Another advantage is that OSM supplies clients with dierent formats. The primary format is XML structured and hence easily readable by human, too. However, XML les can grow very large, which is a downside when it comes to mobile devices. As introduced already, mobile units ought to communicate in 70

our scenario, so the lack of both, processing power and storage space has to be taken into account. OSM provides a binary view on its data, too. This format is geared towards a small size of datasets and thus suitable for mobile devices. Versioned supports the community-based approach as users are able to check and compare current features to older versions. Similar to Wikipedia, mistakes and errors are supposed to be corrected by users who examine changes committed by others on a voluntary basis. As for tool support, the OSM presents a number of editors and viewers for streetmap data. JOSM[IS] is the most powerful editor amongst them and provides all functionality needed to access and alter all kinds of information supported by OSM. In addition, there are editors and interfaces for C++, Flash, and Perl. Besides editors, OSM supplies an interface to the browser in a way to render and display the features stored inside the database. This tool is called Slippy Map and provides insights in all features available. A drawback of OSM is the community-based approach already mentioned. Data is only reliable to a certain extent, but there is no guarantee that all streets featured by OSM are actually absolutely correct, i.e. both route directions and annotations are subject to human mistakes. Data stored by OSM has not necessarily been checked properly as commercial street data was. Furthermore, data might be incomplete in terms of route annotations. Suppose a one-way street which lacks this attribute inside OSM. This would be critical for realistic simulations as simulation results would not allow reviewers to make true conclusions.

A.1.3

Data Structure

The data structure is based on XML in an own format. There are just a couple of elements in the most current version that are linked together as explained below. Each element of the data structure can have the additional attributes timestamp and user to track changes. In addition, features can be hidden by setting the visible attribute. node A node element is a unique feature and refers to a point on earth. Hence its attributes are lat (latitude), lon (longitude), and a unique id. segment A segment consists of two nodes that are referred to as from and to. way A way is a sequence of two or more segments that follow one another. All routes found in OSM are ways, e.g. streets, highways, railways, bus lines, and so on. Ways are dened by nd -subnodes, which reference a node. area An area is a sequence of at least three segments that enclose a certain zone. tag This node has k(ey) and v(alue) as attributes and is essential for us to get information about a street. Amongst the possible key and value pairs, there are street types, street attributes, such as lanes, speed maximum, vehicle access restrictions, and trac signs and signals. relation Relations are used to describe a relationship between several objects. Sub nodes (members) are assigned a role, such as from, to, or at. 71

As a matter of fact, not all of these possible nodes inside a OSM feature le are being used. Datasets we have investigated so far contained only node, way, and tag xml nodes. There has been no usage of segment or relation so far. This might have to do with the new protocol specication 0.5.

A.1.4

Access Options

The OSM database oers convenient access to all features by means of a simple REST[RES] API. Simple requests retrieve all features in a box specied in the request. On the other hand, related features can be retrieved. The following short requests give a brief example of what is possible with the API as specied by the protocol[Groa]. GET /api/0.5/map?bbox=<bllon,bllat,trlon,trlat> The bounding box given species the bottom left and top right corner of the area requested. The OSM system will return all features (nodes, ways) that have a relation to that area. That is, either they are inside or, for instance, at least one node of a way is inside that box. In addition, GPS points can be requested. The area covered by the bounding box is subject to restrictions with regard to size. 50.000 features seems to be the current maximum of nodes that can be retrieved. If more features are needed, users are advised to download the planet.osm le already introduced. GET /api/0.5/node/<id>/ways GET /api/0.5/<objtype>/<id>/relations These requests will return back references to provided features. Suppose you have a node and want to know which ways reference it. GET GET GET GET /api/0.5/ways/search?type=<type>&value=<value> /api/0.5/nodes/search?type=<type>&value=<value> /api/0.5/relations/search?type=<type>&value=<value> /api/0.5/search?type=<type>&value=<value>

The rst three requests specify the type of node they want the OSM system to return. Regarding the rst example with oneway as type and yes as value, OSM will return all ways which are one-way only. Similar to that, suppose the second request with railway as type and station as value. OSM will then return a subset of all nodes stored, which are railway stations. Restricted to a certain area, users could so easily request all railway stations in Berlin, for example. The last request causes the OSM system to search for all kinds of features stored.

A.2

TIGER
written by Martin Wolf

72

A.2.1

Overview

The TIGER system and digital database was developed at the US Census Bureau in order to support its mapping needs for decennial and economic censuses and other Bureau programs. The rst prototype was developed in 1989 mainly based on US Geological Survey topographic maps. Main requirements were that features were properly named, in the correct relationship to each other, and reasonably accurate in scale. In the following years the database was updated and enhanced. The term TIGER is an acronym for Topologically Integrated Geographic Encoding and Referencing. The TIGER database covers the United States and its territories and contains information about their features such as roads, railroads, rivers, political boundaries, and census statistical bounders. Additional information on these features comprises their location in latitude and longitude, the name, the type, address ranges for most streets, and geographic relationship to other features. Out of the TIGER database so called TIGER/Line les were created and made available to the public. These les can be used as the basis for Geographic Information Systems or mapping software. With the modernization of the TIGER systems there will be new spatial data products: Oine distribution: TIGER/Line les in the shapele format (Please refer to the according chapter in this documentation for more information) TIGER/GML1 Online distribution: WebTIGER, a web feature service2 Web Map Service producing maps of spatially referenced data dynamically from TIGER in various graphical formats (png, gif, jpg, svg)

A.2.2

Advantages and Disadvantages

The TIGER data comes from a variety of sources, mainly from the US Geological Surveys 1:100000 topographic maps. Those maps allow a maximum positional error of approximately 50 meters. This accuracy is sucient for the needs of the Census Bureau and their task to count and prole the Nations people and institutions. Other applications may require a higher level of accuracy. Furthermore the latitude and longitude for each place was calculated with reference to the legal boundaries of the entity, not the centre of a collection of buildings (such as the central business district) or a special place (such as the city hall). Another disadvantage is the fact that the TIGER data only covers the US and its territories. Therefore it is only useful for applications with a use case
1 GML is an acronym for Geographic Markup Language which is the XML grammar dened by the Open Geospatial Consortium (OGC) to express geographical features. For more information please see: http://www.opengeospatial.org/standards/gml 2 This OpenGIS standard provides interfaces to access geographical features across the web. For more information please see: http://www.opengeospatial.org/standards/wfs

73

bounded to the US or a use case that abstracts from the real location and only needs a realistic road and rail network. For those applications the TIGER system and its data are a comprehensive source for geographic information. First of all they are free of charge and legal commitments. Moreover in the course of the modernization the TIGER data will be made available in the common shapele format. In addition it is planned to provide a web feature service and a web map service. Both should implement the according standards from the Open Geospatial Consortium.

A.2.3

Data Structure

The TIGER/Line les contain data describing three major types of features: Line features (Roads, Railroads, Boundaries, etc) Landmark features (point landmarks (i.e. schools), area landmarks (i.e. parks)) Polygon features (geographic entity codes, area landmark locations) Information on those features is stored in so called record type les (*.RTn where n is the record type number). In the latest version of the TIGER/Files there are 19 record types that collectively contain geographic information (attributes) such as address ranges and zip codes. Furthermore they contain Add-On codes for street complete chains, names, feature classication codes, codes for legal and statistical entities, latitude/longitude coordinates of linear and point features, landmark features, area landmarks, and area and polygon boundaries. If not all record types are required there are no equivalent les for the county. Special record type elds are used to link together data from dierent record types. An enumeration of all current record types can be found in table A.1. Additional information on the record types and a detailed description of all their elds is provided in the technical documentation3 . On the DVD/CD-Rom as well as in the internet, there is one folder for each state that contains the individual county les as well as a Counts le. For each county or county equivalent there is a le named TGR + 2-digit state FIPS (Federal Information Processing Standards) code + 3-digit county FIPS code. This le is an archive which contains the aforementioned record type les with all the information on the county. The COUNTSnn.txt le (where "nn" is the state FIPS code) shows the counts for the number of records for each record type by county for a state. If the count for a particular record type is 0, then that record type does not exist for that county. All the TIGER/Line les are in ASCII text format only.

A.2.4

Access Options

The last TIGER/Line les (2006 Second Edition) produced from the legacy database are distributed on DVD/CD-ROM and on the Census Bureaus Internet site4 .
3 http://www.census.gov/geo/www/tiger/tiger2006se/TGR06SE.pdf 4 http://www.census.gov/geo/www/tiger/tiger2006se/tgr2006se.html

74

Record Type 1 2 4 5 6 7 8 A B C E H I M P R S T U Z

Description Complete Chain Basic Data Record Complete Chain Shape Coordinates Index to Alternate Feature Identiers Complete Chain Feature Identiers Additional Address Range and ZIP Code Data Landmark Features Polygons Linked to Area Landmarks Polygon Geographic Entity Codes: Current Geography Polygon Geographic Entity Codes: Corrections Geographic Entity Names Polygon Geographic Entity Codes: Economic Census TIGER/Line ID History Link Between Complete Chains and Polygons Feature Spatial Metadata Record Polygon Internal Point TIGER/Line ID Record Number Range Polygon Geographic Entity Codes: Census 2000 TIGER Zero-Cell ID TIGER/Line ID Overpass/Underpass Identication ZIP+4 R Codes Table A.1: TIGER record types

Tiger/Line data in shapele format can already be downloaded from the ESRI internet site5 . In future those les will also be available on the US Census bureau site. Furthermore a web feature service and a web map service providing geographic data respectively there graphical representation will be made available to access the TIGER data over the internet.

A.3

ESRI Shapele
written by Bernd Schufele

A.3.1

Overview

ESRI Shaple is a data standard for nontopoligical geometry[Ins]. Besides the actual shaples that contain the geometrical data, also a dBase database for additional information, such as street names, and an index le belong to the Shapele standard. The database scheme is not specied in the standard, it is specic to the producer and vendor of the data. Shapele was developed by the Environmental Systems Research Institute (ESRI), a company that is specialized on software products for creating, editing, and publishing geographical information. ESRI sells in its format the street data of Tele Atlas and NAVTEQ, the two most important providers of street map data in 2007. Due to the availability of this data in the Shapele format, this
5 http://arcdata.esri.com/data/tiger2000/tiger_download.cfm

75

standard is used by many vendors of mobile navigation systems. As map data in the Shapele format is a commercial product of ESRI and as it is used by mobile navigation system vendors, there is not much free geographical data available.

A.3.2

Advantages and Disadvantages

There are several advantages of the usage of Shapele. ESRI sells very detailed map data of the whole world. This data contains streets and additional information, e.g. trac signs and signals. The data of ESRI fullls highest requirements. This is proven by the fact that is used for many car navigation systems. Another advantage arises from the wide usage of Shapele. It is a de facto standard for geographic data. There is a lot of software available that supports the Shapele standard. Besides the commercial products of ESRI, there are also many free tools and libraries for creating and editing of shapeles. In this project the SUMO simulator is used for the simulation of trac networks. SUMO can import shapeles and run simulations on them. They can also be watched in the graphical viewer GUISIM. As the SUMO simulator already supports Shapele, no additional work must be done to integrate the map data into the simulation. An important factor in simulations is their temporal behavior. Therefore another advantage of Shapele is its data format. Shapeles contain just binary data, which does not have the overhead that other structured data formats, such as XML, have. Hence shapeles can be parsed and processed rather fast. Moreover no topological data is stored in Shapele. Topology means the spatial relationship[Ins] between dierent map elements. For instance in a topological data structure the entry for an arc also contains its surrounding polygons, while in nontopological data an arc only consists of its two end points. This additional topological information, which is not required for simulations, would also cause processing overhead. This is an obvious advantage of Shapele compared to data formats with topological data. Another positive side eect of the binary format and the lack of topological information is the demand of little disk space. Although this looks very promising, there are several reasons why Shapele is not suitable for our purpose. The major problem is that Shapele is a commercial product. As a consequence of that there is hardly any free map data available. The few gratuite data resources that exist are not useful as the data is either not precise or from areas that are not suitable for trac simulations. The binary format which at rst view is an advantage due to its processing speed, also causes problems. To write or parse shapeles is cumbersome compared to XML data formats. Furthermore XML data is also human-readable to a certain degree, while the binary format of Shapele is not at all. Hence it is rather dicult to nd errors in corrupt shapeles.

A.3.3

Data Structure

A Shapele data set consists of three elements, the actual shapele which contains geometrical data, a dBase database with additional attributes and an index le for fast navigation in the shapele. While the shapele and the index le are dened exactly in the Shapele standard, the scheme of the database is not specied and vendor specic. 76

A shapele can contain one of the following shape types: Null Shape Point Multipoint (Set of points) Polyline (Set of lines) Polygon (Can contain one or more rings, i.e. closed sequences of lines) PointM (Point with a measure value, i.e. an additional numeric value) MultipointM (Set of points with one measure value per point) PolylineM (Set of lines with one measure value per point) PolygonM (One or more rings with one measure value per point) PointZ (3-D point with a measure value) MultipointZ (Set of 3-D points with one measure value per point) PolylineZ (Set of 3-D lines with one measure value per point) PolygonZ (One or more 3-D rings with one measure value per point) Multipatch (Number of surface patches, i.e. triangles or polygonal rings) A shapele can contain only one single shape type. For that reason several shape types have to be saved in dierent les, which should have a common le name prex. For example the points of geographical data that represents Berlin, could be stored as berlin.points.shp, while the streets could be stored as berlin.polyline.shp. The rst entry in a shapele is a 100 bytes long header. This header species the length of the le, the shape type that it contains and a bounding box for the elements. Each data record entry has a header that is eight bytes long. The rst four bytes are used for the number of the entry, the other eight bytes for the length of the content of the entry. As in the future, shapeles may be allowed to contain more than one shape type.""[Ins], each record entry begins with a four byte eld that shows the shape type, although the shape type is already specied in the header of the le. The actual data entries are specic for each shape type. Besides the null shape, which is only a placeholder, the most simple type is a point. A point is always a 20 bytes long data entry, four bytes for the shape type,eight bytes for the X value, and eight bytes for the Y value. Other shape types are more complex. For instance a polyline contains an array of points and an array of line parts, which are actually indexes to the rst point of the part in the points array. Ahead of that it must be dened how many parts and points will follow and a bounding box for the polyline must be given. This example shall show the complexity of shapele entries. The specication for other shapetypes can be found in [Ins]. For each shapele there is exactly one dBase database. The database must have the same lename like the shapele, but with the le extension .dbf. For 77

instance if the shapes are stored in the le berlin.points.shp, the database must be called berlin.points.dbf. For each data record entry in the shapele, there is exactly one entry in the database. The order in the database table is the same like in the shapele. Beyond that the Shapele standard does not specify the database. It is open to the vendor, what is stored in the database and which database scheme is used. The third le that is dened in the Shapele standard is the index le. This index le can be used to parse the shapele faster. An index le must have the le extension .shx and the same le name like the shapele that it belongs to. Index les also begina with a le header, which is identical in organization[Ins] to the header in data les. The header is followed by index entires. There are exaxtly as much index entries in the index le as data entries in the shapele. Furthermore the order of entries in the index le is exactly the same like in the data le. Each of these index le entries is eight bytes long. The rst four bytes hold the oset of the data le entry with respect to the beginning of the data le. The latter four bytes contain the length of the data le entry.

A.3.4

Access Options

There are some sources for free shapeles, but they are all not very detailed or from unsuitable areas. One major data source are the les from Census 2000 TIGER/Line Data [otC]. These les contain only map data about the USA (see chapter 3.2). Furthermore the TIGER les unfortunately cannot be accessed by an interface, but can only be downloaded from the web site. ESRI also oers free map data of the whole world. This data can also be downloaded from the ESRI web page. However this data is not very detailed, as it does not provide information on street level, but only on city level. Moreover just like for the TIGER les, there is no interface to obtain this data comfortably out of our own software. The desired area has to be selected in an online map, for which a download archive with the les is created. Another source are les from the Unesco[Une]. These les can also be downloaded from a web page. Unfortunately only data from areas in Namibia can be downloaded. Moreover the data seems to be in a corrupt format that cannot be imported into SUMO. There are several more sources of shapeles on the internet. These few examples, which belong to the best sources for shapeles, shall demonstrate that it is not possible to obtain adequate data for free. Shapele is a common standard for geometrical data. Therefore implementations in many widespread programming languages are available. There are libraries for languages such as C, C++, Java, Python, Perl, Delphi, .NET, PHP, Ruby[War]. The availability of libraries for so many languages provides easy integration of shapeles into own programs.

A.4

SUMO Formats
written by Martin Beck

78

A.4.1

Overview

SUMO[DK] takes its input from several les in an XML format. This section describes the required and optional elements of them. It starts with the nodesle which contains point denitions. These nodes are connected to edges in an edges-le representing small parts of streets. To avoid redundancy when dening attributes like number of lanes for each streetpart, edges can have types which are described in a type-le.

A.4.2

Node File

A node-le contains the tag <nodes> as the surrounding tag. In its inner body several nodes can be dened by using a <node>-tag. One node requires three attributes: a unique id and a position, represented in kartesian coordinates. Geographical coordinates can also be used, but need an extra parameter while using netconvert to interprete the input les. An optional attribute is the type of a node, which can alternatively be priority (which is the default) or trac_light. Priority means, that a possible crossroad at this node gives right-of-way to the car coming from the edge with a higher priority. If they have the same priority, left yields to right. Obviously, trac_light denes this crossroad as having a trac light. element node attribute id x y [type] meaning unique id x-coordinate y-coordinate priority(default): priority-based right-of-way trac_light: crossroad with trac light

Table A.2: Nodes-le elements

A.4.3

Edge File

An edge-le connects the nodes from the nodes-le to a network of streets. Its surrounding tag is <edges> and it contains several <edge> elements each of them dening one edge between two nodes. This edge is a one-way road, thus for having cars driving in both directions, a second edge has to be denied vice-versa. Required attributes for an edge are its unique id and two nodes identifying the start and the end point of the edge. Instead of these nodes, two cartesian points can also be set, but using this feature is not recommended. Optionally, an edge can contain attributes specifying the number of lanes on it, its maximum speed in meters per second, its priority and its length in meters. Additionally spread_type can be used to tell SUMO, whether the lanes of the edge should be centered around it or created at the right side of it. To save space, all these attributes can be aggregated as a type in the types-le. With the attribute type, the edge can automatically use these values but is able to override some of them if needed. Two other attributes, shape and function are possible, but are not needed in this scenario. 79

attribute id f romnode tonode [type] [nolanes] [speed] [priority] [length] [spread_type]

meaning unique id start node of edge end node of edge type of edge, refers to type le number of lanes for this edge maximum speed on the edge in meters per second priority of the edge length in meters center : lanes centered around edge right: lanes at the right side of edge Table A.3: Edge attributes

default

1 13.9 calculated by number of lanes and maxspeed calculated as Euclidean distance of nodes center

A.4.4

Type File

A types-le groups the edge attributes number of lanes, maximum speed and priority as types, which can be reused by multiple edges in the edges-le. The surrounding tag is <types>, a type itself is dened within a <type> element. Obviously, the attributes have the same meaning as they have in the and egde denition. attribute id [nolanes] [speed] [priority] meaning unique id number of lanes for this edge type maximum speed on the edge type in meters per second priority of the edge default 1 13.9 calculated by number of lanes and maxspeed

Table A.4: Type attributes

80

User

:DatabaseMenu

:DatabaseAccess

Export to database exportToDb() checkSchema()

ref checkSchema

alt [number of tables > 0| true

[else] false setSchema()

ref setSchema

ref save

Figure A.1: General dabase export control ow

81

Appendix B

UML Models

82

User

:DatabaseMenu

:DatabaseAccess

Database

:InternalDB

Import from database

importFromDB()

load() <<create>> :Hibernate Session connect

start transaction

ack

loadMapData() loop

create queriy load

for each type of map data database entries update progress bar object list save(list)

show in map display

loadEventData()

loop for each type of event data

create queriy load

database entries update progress bar object list

save(list)

show in map display

commit() close

ack

Figure B.1: Database import control ow

83

checkSchema

:DatabaseAccess <<create>> :Hibernate Session connect start transcation ack

:Database

createQuery()

commit() ask for number of tables

Figure B.2: Check, if the database is empty

84

setSchema

:DatabaseMenu

:DatabaseAccess <<create>> parse schema file :Hibernate Session

:Database

loop for each parsed query start transcation

connect

ack

createQuery()

commit() execute query

update progress bar

Figure B.3: Control ow for the setting of the schema

85

save

:DatabaseMenu

:DatabaseAccess

Database

save() <<create>> :Hibernate Session

start transaction connect

ack flush()

createSQLQuery (truncate all tables)

saveMapData()

loop for all map data objects in internal db update progress bar

save(object)

saveEventData()

loop for all event data objects in internal db update progress bar

save(object)

execute all statements commit

Figure B.4: Database saving control ow

86

Appendix C

Legacy Features
written by Florian Thomas

There are some features that are not longer supported by eWorld. Although, the corresponding documentation is kept in this chapter. If further developers decide to reintegrate them, they can use it as the basis.

C.1

eWorld - Export to VanetMobiSim

C.1.1

Overview

eWorld also allows for exporting to the trac simulator VanetMobiSim [HF]. This simulator is not as sophisticated as SUMO. Hence, there are some restrictions for the export les. Unfortunately, not all features of eWorld can be used in VanetMobiSim les. This section describes, how the export is designed and implemented. VanetMobiSim les are XML les and the classes for the creation of the XML code is generated with the JET template enginge [jet]. JET comes with the Eclipse Modeling Framework, which can be downloaded from [emf]. In order to use the JET template engine, the Eclipse project must be converted into a JET project. This can be done by clicking with the right mouse button on the project, and choosing new -> Other -> Java Emitter Templates -> Convert Projects to JET Projects. Now the project settings contain a new entry JET settings. There the source folder of the project and the template folder can be specied. In eWorld, the source folder is src and the templates are stored just in templates. The JET template is in the le eWorld2VanetMobisimTemplate.xmljet. It consists mainly of XML code, enriched with some Java instructions. The structure of VanetMobiSim XML les is as follows. The whole le is enclosed by the root node <u n i v e r s e> [...] </ u n i v e r s e> 87

After that the size of the net must be specied, which is dened by <dimx>v a l u e</dimx> <dimy>v a l u e</dimy> Values bigger than 1000 seemed to lead to problems in VanetMobiSim. Subsequently the length of the simulation can be set with

<e x t e n s i o n c l a s s=" de . u n i _ s t u t t g a r t . i n f o r m a t i k . canu . mobisim . s i m u l a t i o n s . Tim where value is the time in milliseconds. Some parameters of the simulation can be set with

<e x t e n s i o n c l a s s=" de . u n i _ s t u t t g a r t . i n f o r m a t i k . canu . s p a t i a l m o d e l . c o r e . S p a t i a <m a x _ t r a f f i c _ l i g h t s>47</ m a x _ t r a f f i c _ l i g h t s> < r e f l e c t _ d i r e c t i o n s>t r u e</ r e f l e c t _ d i r e c t i o n s> <number_lane f u l l =" f a l s e " max=" 64 ">1</ number_lane> </ e x t e n s i o n> The rectangle of the simulation can be dened, where again values that exceeded 1000 caused problems. Unfortunately, VanetMobiSim does not provide means to set trac lights at specic crossroads on the map. Only the maximum overall number of trac lights in the network can be dened. Hence in the implementation we count the number of trac lights in the eWorld map. Moreover, single streets cannot be declared as one-way- or two-way street. Either all streets are one-way-streets or none. Similar problems exist with the number of lanes per edge. It can only be specied, which is the maximum number of lanes (1 here), and how many edges have this maximum number (64 here). After that, the step length of the trac lights must be specied: <e x t e n s i o n c l a s s=" eurecom . s p a t i a l m o d e l . e x t e n s i o n s . T r a f f i c L i g h t " s t e p=" 10000 " /> Subsequently, the net can be build with <e x t e n s i o n c l a s s=" eurecom . u s e r g r a p h . UserGraph " name=" userGraph "> <v e r t e x> <i d>68 cd79</ i d> <x>667</x> <y>755</y> </ v e r t e x> <edge> <v1>15 c 9 7 e 4</ v1> <v2>10 f 0 6 2 5</ v2> <s p e e d>50</ s p e e d> [...] </ e x t e n s i o n> Finally, the starting positions and trips of the cars are denoted with

<e x t e n s i o n name="PosGen" c l a s s=" de . u n i _ s t u t t g a r t . i n f o r m a t i k . canu . t r <e x t e n s i o n name=" TripGen " c l a s s=" de . u n i _ s t u t t g a r t . i n f o r m a t i k . canu . t r i p m < r e f l e c t _ d i r e c t i o n s>t r u e</ r e f l e c t _ d i r e c t i o n s> <minstay>2 0 . 0</ minstay> <maxstay>1 0 0 . 0</ maxstay> </ e x t e n s i o n> <nodegroup n=" 50 "> <e x t e n s i o n c l a s s=" p o l i t o .uomm.IDM_IM" i n i t p o s g e n e r a t o r="PosGen" <minspeed>1 0 . 0</ minspeed> <maxspeed>2 0 . 0</ maxspeed> <s t e p>0 . 1</ s t e p> <b>0 . 5</b> </ e x t e n s i o n> </ nodegroup> 88

The g i v e n v a l u e s proved a s r a t i o n a l f o r normal t r a f f i c l i g h t s i m u l a t i o n s . Nodegroup \ b e g i n { l s t l i s t i n g } [ l a n g u a g e= XML] <e x t e n s i o n c l a s s=" de . u n i _ s t u t t g a r t . i n f o r m a t i k . canu . mobisimadd . e x t e n s i o n s . GUI"> <width>1000</ width> <h e i g h t>1000</ h e i g h t> <s t e p>1</ s t e p> </ e x t e n s i o n> The template le reects this XML structure. Additional Java instructions begin with <%. At the top of the le, the package, into which the template le shall be compiled is given, it is the package de.hpi.eworld.extensions.export.vanetmobisim. Changes in the le are compiled on-the-y into the Java le.

C.1.2

Implementation

All les of the VanetMobiSim export are organized in the package de.hpi.eworld.extensions.export.vanetmobisim. It mainly consists of the les EWorld2VanetMobisimMenu, which is the entry point of the plugin, EWorld2VanetMobisim, which controls the export and preprocesses the data for the export and EWorld2VanetMobisimTemplate, which is le that is generated out of the template. EWorld2VanetMobisimMenu is a slim user interaction class. At the startup, it generates a menu entry. When the user requests to requests to export the data, the corresponding callback method is called. In this, a le dialog window is opened, that gives the user the possibility to specify the le name. If a valid le name is given, the output generation in the class EWorld2VanetMobisim is started. In the generation method in EWorld2VanetMobisim, rst the numbers of nodes and traclights are counted and the maximum x and y values are determined. As values greater than 1000 made VanetMobisim crash, the maximum x and y values are recalculated, so that the bigger of them is 1000. After that, the number of edges with more than one lane is counted and the average number of lanes per edge is calculated. The number of cars is set to a maximum of 50 to keep the simulation running smoothly. If there are less than 50 nodes in the net, the number of cars is restricted to the number of nodes. Before creating the XML stream, a new projection in eWorld is set, the VanetMobisimProjection, which basically recalculates the x and y values of all nodes, so that they are proportional to the net size limit of 1000. The data, that was gathered, that is, the size of the net, the number of trac lights, the number of lanes with more than one edge, the average number of lanes per edge, the nodes and edges and the number of cars. With this information, the generated class is called to produce the XML output stream. After that, it is written into the given le. Finally, the original projection of eWorld is reset, as it is required by other parts of the application.

89