# OpenStreetMap-Integration

**Copied from the SimRunner-Project**

This movement model can load map-data from different sources (OpenStreetMap-data is preferred, because OpenSource). In this project you can change/specify two things:

+ Change parameters of the simulation. E.g. which map-provider provides the map-data or which type of POIs (Points of Interest) should be loaded. The whole configuration part is made in the file "config/social/SocialTest.xml"
+ In the folder "osm" are some files. Some files can be loaded from the project, some are temporary files and some are cached values, which can be reused at the next start

OSM-PBF-files for Darmstadt: http://download.bbbike.org/osm/bbbike/Darmstadt/
General: http://download.bbbike.org/osm/bbbike/


## Configuration via SocialTest.xml

In this file you can specify all necessary parameters. In the upper fields you have to specify some variables, which are then used by multiple class-instances:

+ **LonCenter**: Specify the center longitude value of the area you want to show/use {Value can vary from -180.0 to 180.0}
+ **LatCenter**: Specify the center latitude value of the area you want to show/use {Value can vary from -90.0 to 90.0}
+ **Zoom**: Specify the zoom level for the wanted area. If you choose Google as the map provider, the zoom level can be chosen from 0 (large extract, whole world) to 18 (small extract, some houses). The specified class `GPSCalculation` gets the center-values and zoom-level and computes the bounding box. All other classes can query the values they need (bounding box or centered calues with zoom)
+ **MapQuestKey**: The standard provider for static map (images) is MapQuest [MapQuest-Developer-Site](https://developer.mapquest.com/ "MapQuest-Developer-Site"). This provider has a free model with 15000 requests/month. To get access to the MapQuest API, we created a user account (User: kom, Password: testtest2015). You can also get the routing via the MapQuest API, but for each node in the simulation you need one requested routed. With this type of routing you will reach the 15000 requests very fast ;)

The next few subchapters explain the configuration of each possible class:


### AttractionGenerator ###
The `AttractionGenerator`-Interface provides a method to load some POIs (or also named attractions) with their corresponding GPS-values. Currently we have two implementations for this purpose:

#### JSONAttractionGenerator ####
This class (`de.tud.kom.p2psim.impl.topology.movement.modularosm.attraction.JSONAttractionGenerator`) loads the POIs out of a specified JSON-file. It needs only two parameters:

+ NumberOfAttractionPoints: Set the amount of POIs you want to use in the simulation
+ PlacementJsonFile: Set the path to the json-file

The data in the json-file is generated by an online-API. With the sample-query for "bar"-POIs in Darmstadt (Bounding Box from [49.4813, 8.5590] to [49.9088, 8,7736]
[Overpass-POI-Query](http://overpass-api.de/api/interpreter?data=%5Bout:json%5D;node%5Bamenity=bar%5D%2849%2E4813%2C8%2E5590%2C49%2E9088%2C8%2E7736%29%3Bout%3B "") you will retrieve a page full of json-data. Simply copy all data and store it in a file. 

#### OnlineJSONAttractionGenerator ####
This class (`de.tud.kom.p2psim.impl.topology.movement.modularosm.attraction.OnlineJSONAttractionGenerator`) loads the POIs live via internet over the overpass-api (which uses osm-data). It needs three parameters:

+ NumberOfAttractionPoints: Set the amount of POIs you want to use in the simulation
+ Amenity: The type of POI you want to extract. Possible amenities are: bar, school, university, college, or club
+ PlacementJsonPath: Set the path, where the live loaded data can be stored and cached. If you don't change the GPS- and amenity-parameters till next start, the class will load the stored data in this path instead of lodaing it again over the internet


### TransitionStrategy ###
This interface is copied from the SocialGraph-project. You can specify the type of SocialGRaph and the so called socialFactor. These values influence how the nodes in the simulation interact.


### LocalMovementStrategy ###
The `LocalMovementStrategy`-interface provides a method to compute routing-information for each node. The nodes walk a step in the simulation and then request this class for the next position they should went to. Severall implementations of this interface are already available. But they do not consider the real world map data (streets etc.), where the nodes could walk/drive. For this purpose we wrote two implementations, which does exactly this:

#### RealWordlSreetsMovement ####
This class (`de.tud.kom.p2psim.impl.topology.movement.local.RealWorldStreetsMovement`) does load the routing information out of a provided osm-data file. If the available data in the osm-file does not have enough information to route a node, the node will stay at its place (e.g. when the available data only covers Darmstadt, but you want to route in Frankfurt). The following values can be specified for this class:

+ OSMFileLocation: Set the path to the osm-data-file, map files of many big cities can be downloaded from https://mapzen.com/data/metro-extracts/
+ GraphFolderFiles: The routing engine stores some temporary data in this folder. If you change some of the parameters, the engine will get in trouble. Simply then delete the content of the folder before starting the simulation.
+ MovementType: The routing enginge can walk through the world as a pedestrian, by bike or by car. The possible values are {foot, bike, car}
+ NavigationalType: You can specify in which mode the routing engine should calculate the best way to the destination. Possible values are {fastest, shortest}
+ MaxDistanceNextPoint: The routing engine provides a list of gps-coordinates, where the node should go along. With this value you can specify how near a node should come to the next position in the routing-list, so that it will point to the next position in the list. A value near 0.0 means that the node has to reach the next point in list very exactly, a value over 10.0 means that the node will point to the next position as soon as it 10 or less meters away from the actual point. With a higher value the node will make some movements, which are not possible in reality (go through houses), but with a small value you can ran in problems, if the node never reaches the specified distance to the next point. The standard value for this parameter is set to 1.0 meters.

#### OnlineMapQuestMovement ####
This class `de.tud.kom.p2psim.impl.topology.movement.local.OnlineMapQuestMovement` loads the routes online via the MapQuest-API. This means you can query any possible route on the world. The disadvantage of the live-request is the delay. The system makes one request per node, which can lead to a few seconds till all routes have been loaded. And you also have to take care of the maximum of 15000 requests per month. The following values can be specified:

+ MovementType: This is a mixture of the MovementType and NavigationalType of the `RealWordlStreetsMovement`-class. You can either calculate the route as a pedestrian, by bike or by car. Via car you have the two possibilities shortest and fastest. The possible values are {Fastest, Shortest, Pedestrian, Bicycle}
+ MapQuestKey: To make queries against the MapQuest-API we need the MapQuest-Key, which is already set as a global variable at the beginning of this configuration-file
+ MaxDistanceNextPoint: The routing engine provides a list of gps-coordinates, where the node should go along. With this value you can specify how near a node should come to the next position in the routing-list, so that it will point to the next position in the list. A value near 0.0 means that the node has to reach the next point in list very exactly, a value over 10.0 means that the node will point to the next position as soon as it 10 or less meters away from the actual point. With a higher value the node will make some movements, which are not possible in reality (go through houses), but with a small value you can ran in problems, if the node never reaches the specified distance to the next point. The standard value for this parameter is set to 1.0 meters.


### MapVisualization ###
The `MapVisualization`-interface provides a method to load an image of a map, which then can be used as a background in the simulation. For this purpose we implemented two classes. One class gets the data from Google, the other one from MapQuest.

#### ShowGoogleMapsViz ####
This class (`de.tud.kom.p2psim.impl.topology.movement.modularosm.mapvisualization.ShowGoogleMapsMapViz`) simply uses the GPS-data from the specified center and zoom-level and queries an image of this world-extract via the Google StaticMap-API. Only one parameter can be set for this class:

+ TempImageFilePath: The class loads and stores the image in this given folder. If no parameter is changed till next start, it will simply use this cached image instead of loading a (exactly same) new one over the internet.

#### ShowMapQuestMapViz ####
This class (`de.tud.kom.p2psim.impl.topology.movement.modularosm.mapvisualization.ShowMapQuestMapViz`) simply uses the GPS-data from the specified center and zoom-level and queries an image of this world-extract via the MapQuest-API. The following parameters can be set:

+ TempImageFilePath: The class loads and stores the image in this given folder. If no parameter is changed till next start, it will simply use this cached image instead of loading a (exactly same) new one over the internet.
+ MapQuestKey: To make queries against the MapQuest-API we need the MapQuest-Key, which is already set as a global variable at the beginning of this configuration-file
+ MapType: You can specify which type of a map the image should have as a background. The value `map` loads a background with computer generated colors and also labels at big streets or cities. The value `sat` loads a real image of the extract. The value `hyb` loads also the real image with some labels.