Merge branch 'master' of https://github.com/livelycode/routing

Conflicts:
	src/store.erl

Author: Haykuhi

docs/Performance Log.md

@@ -0,0 +1,15 @@
+#Performance Log
+
+Test of in-memory database alternatives. The time for the same request was measured for each database.
+
+Request: http://127.0.0.1:2904/route?from=26999575&to=275283807
+##Using ETS
+"time":211519
+##Using Membase
+###mcd library
+"time":19172683
+###merle library
+"time":17069207
+##Using Redis
+###eredis library
+"time":8140534

docs/api.md

@@ -8,7 +8,7 @@ Starts the routing system.
 Stops the routing system.
 
 ### load_osm_data(File)
-Loads OpenStreetMap data from a .osm file. The system needs to be stopped first.
+Loads OpenStreetMap data from a .osm file. The system needs to be started first.
 
 # HTTP APIs
 ##Route

docs/report.md

@@ -1,54 +1,161 @@
 # OSM Routing
 
 ## Projektziel
+Ziel des Projektes ist die Schaffung der technischen Infrastruktur, welche die Entwicklung eines Navigationssystems für körperlich behinderte Menschen ermöglicht.  
+Es soll möglich sein, den kürzesten Weg zwischen zwei Nodes eines OpenStreetMap Datensets zu ermitteln.  
+Der ermittelte Weg soll von einem Menschen mit körperlicher Behinderung komplett begehbar sein.  
+Das System soll ausserdem eine Wegbeschreibung des ermittelten Weges generieren.
 
 ## Architektur
 Im folgenden wird eine Übersicht über die Architektur des Systems gegeben. Dazu gehören ein Diagramm über die einzelnen Softwaremodule, eine Beschreibung des Ablaufs einer Anfrage sowie eine Übersicht über die verwendeten Erlang Module.
 
-### Diagramm
+
 ![Overview](routing.pdf)
 
 ### Bearbeitung einer Anfrage an das System
+1. HTTP Anfrage wird gesendet.
+2. Der Server erhält die Anfrage. Die Bearbeitung der Anfrage übernimmt das Erlang System.
+3. server:request() wird  aufgerufen. Diese Funktion dient der Erkennung der Art der Anfrage und zur Weiterleitung an die entsprechenden Submodule.
+4. requests:route() wird aufgerufen. Diese Funktion berechnet die Route der Anfrage. Dies geschieht mithilfe der Funktionen des astar Erlang moduls.
+5. Die Funtionen aus dem astar Modul greifen zur Berechnung der Route auf das geodata Erlang Modul zu. Das geodata Modul dient als High-Level API für die Datenbank. Alle Anfrage des geodata Moduls an die Datenbank laufen über das store Modul, welches als Low-Level API für diese dient.
+6. Nachdem die Route berechnet ist wird die HTTP Antwort in JSON enkodiert. Anschliesend sendet die Funktion server:request() die HTTP Antwort.
 
 ### Erlang Module
 #### astar
+Dieses Modul implementiert einen A* Algorithmus, um den kürzesten Weg zwischen zwei Knoten zu finden.
+
 #### geodata
+Diese Modul dient als High-Level API für die Datenbank. Alle Zugriffe auf die Datenbank laufen über dieses Modul.
+
 #### osm_parser
+Mithilfe dieses Moduls ist es mögich eine .osm Datei auszulesen und deren Inhalt in der Datenbank zu sichern.
+Die Daten werden beim Einlesen über generische Regeln gefiltert. So lassen sich leicht für Behinderte ungeignete Wege aus dem Datenset entfernen.
+
 #### priority_queue
+Dieses Modul implementiert eine Prioritätswarteschlange, welche vom Routing-Algorithmus benötigt wird.
+
 #### requests
+Dieses Modul implementiert die HTTP Antworten des HTTP Servers.
+
 #### routing
+Dieses Modul dient als Schnittstelle für das komplette System. Andere Erlang Systeme sollten über diese Schnittstelle mit dem Routingsystem kommunizieren.
+
 #### server
+Dieses Modul implementiert die HTTP API des Servers. Es ist nur die Serverlogik und die JSON Serialisierung enthalten.
+
 #### store
+Dieses Modul dient als API der ets Tabellen. Die ets Tabellen sollten nur über diese API angespochen werden.
 
 ## Softwarekomponenten
 ### Programmiersprache
-Die Wahl der Programmiersprache viel auf Erlang.
+Die Wahl der Programmiersprache des Backends viel auf Erlang.
 
-Pro:
+PRO:
 
 * Virtuelle Maschine:
-Erlang läuft auf einer VM. Damit ist es sehr leicht möglich ein Programm zu ändern, während es läuft, ohne es komplett neu zu kompilieren und neu zu starten. Dies erhöht die Produktivität. 
-
+Erlang läuft auf einer VM. Damit ist es sehr leicht möglich ein Programm im laufenden Betrieb zu ändern, ohne es komplett neu zu kompilieren und neu zu starten. Dies erhöht die Entwickler-Produktivität.
+ 
 * Referenzielle Transparenz:
-Da der einzige Effekt einer nebeneffektfreien Funktion ihr Rückgabewert ist, sind Sie leichter zu verstehen als Prozeduren.
+Da der einzige Effekt einer nebeneffektfreien Funktion ihr Rückgabewert ist, ist Sie leichter zu verstehen als eine Prozedur.
 
 * Deklarative Sprache:
 Erlang ist eine Deklarative Sprache. Im vergleich zu imperativen Sprachen führt das zu kürzeren, leichter verständlichen Programmen.
 
 * Leichtgewichtige Prozesse:
 Prozesse sind Teil der Erlang VM und nicht Teil des Betriebssystems. Dadurch sind Sie wesentlich leichtgewichtiger als OS Prozesse oder sogar Threads. Auf einem handelsüblichen Rechner ist es möglich mehrere hundertausend Erlang Prozesse laufen zu lassen. Damit ist Erlang optimal für ein asynchrones und ausfallsicheres System geeignet.
 
-
-Kontra:
+KONTRA:
 
 * Performancekritischer, sequentieller Code:
-Durch die Indirektion der VM geht ein Teil der Performance der Hardware verloren. Obwohl der grösste Teil des Systems durch IO Operationen dominiert wird, gibt es kleine performancekritische, sequentielle Code Stücke (z.B. der routing Algorithmus). Hier könnte man durch eine Hardwarenhe Sprache wie C eine verbesserte Abtwortzeit erreichen.
+Durch die Indirektion der VM geht ein Teil der Performance der Hardware verloren. Obwohl der grösste Teil des Systems durch IO Operationen dominiert wird, gibt es kleine, performancekritische, sequentielle Codestücke (z.B. der routing Algorithmus). Hier könnte man durch eine Hardwarenahe Sprache wie C eine verbesserte Antwortzeit erreichen.
 
 ### Datenbank
+
+Als Datenbank werden mehrere ets Tabellen verwendet.
+
+* http://www.erlang.org/doc/man/ets.html
+
+PRO:
+
+* Einfache API:
+Da ets Tabellen einfache Key-Value Stores sind, sind Sie sehr einfach zu benutzen.
+
+* Erlang Modul:
+ets Tabellen sind Teil des Erlang Systems. Damit sind Sie direkt über Erlang Syntax verwendbar. Darüber hinaus werden die Abhängigkeiten des Systems nicht unnötig erweitert.
+
+* In-Memory Datenbank:
+ets Tabellen werden komplett im Hauptspeicher gehalten. Zugriffe auf die Tabellen sind damit sehr schnell.
+
+KONTRA:
+
+* Speicherverbrauch:
+Da alle Tabellen komplett im Hautspeicher gehalten werden, verbrauchen diese viel Platz. Es ist somit nicht möglich extrem grosse .osm Dateien einzulesen.
+
 ### Algorithmus
-### HTTP Server
+Zur Berechnung der kürzesten Route zwischen zwei Knoten wird der A-Star Algorithmus verwendet.
+
+PRO:
+
+* Einfach
+A-Star ist leicht zu implementieren. Sämtliche in vergleichbaren Systemen implementierten Algorithmen basieren auf A-Star mit zusätzlichen Optimierungen.
+
+KONTRA:
+
+* Speicherbedarf
+Da alle besuchten Knoten in einer Liste gahelten werden, benötigt A-Star im worst-case sehr viel Speicher.
+
+### HTTP API
+Das gesamte System wird über eine HTTP Schnittstelle angesprochen.
+
+PRO:
+
+* Universelle API:
+Sowohl lokale Anfragen als auch Netzwerkanfragen können über eine API getätigt werden.
+
+* Einfache API:
+HTTP Anfragen sind sehr einfach zu stellen. Es existiert zu jeder populären Sprache ein entsprechendes Modul.
+
+KONTRA:
+
+* Nichts (bei der Art des Systems).
+
+##Performanz-Tests
+Ausgewertet wurden verschiedene Metriken von drei Routen unterschiedlicher Länge:
+
+| Metrik | Rohrbach - Uni | OMZ Uni - Mensa Uni | OMZ Uni - Mannheim |
+| -			| -				| - | - |
+| Zeit	| 82 ms | 190 ms	 | 1520 ms |
+| Nodes in Ergebnis | 20 | 25 | 71 |
+| Pfadlänge | 460 m | 4151 m | 17 866 m |
+| Besuchte Nodes in Algorithmus | 451 | 2550 | 15816 |
+| Speicherbedarf | 44 k words | 220 k words | 1338 k words |
+
 
 ## Weiterentwicklung
 ### Geochouch
+Es bietet sich an, das Routing-System an GeoCouch anzuknüpfen. GeoCouch ermöglicht die Berechnung von Bounding-Box Anfragen, welche für eine weitere Verbesserung der Wegbeschreibung und einen fortgeschrittenen Name-Server nötig sind.
+Da GeoCouch/CouchDB ebenfalls in Erlang implementiert wurde, ließe sich das Routing System sogar zu einem CouchDB-Plugin entwickeln. Das hätte den Vorteil einer schnelleren Daten-Zugriffszeit und würde das Deployment erleichtern.
+Ein mit GeoCouch gebundeltes Routing System bietet beste Vorraussetzungen zur Entwicklung von Routing-Webapps. Der Entwickler dieser Apps müsste lediglich JavaScript und HTML beherrschen, da die komplette Backend-Funktionalität von GeoCouch abgedeckt werden kann.
+
+* https://github.com/couchbase/geocouch
+* http://www.couchbase.org/
+
+###GeoJson
+Sämtliche APIs des Routing-Systems sollten auf GeoJson standardisiert werden. GeoJson ist ein leichtgewichtiger Standard für Geo-Daten, der sich wachsender Beliebtheit in der Webentwicklung erfreut.
+Die Standardisierung würde die Verwendung vor allem von UI-libraries deutlich erleichtern.
+
+* http://geojson.org/
+
 ### Polymaps
-### Algorithmus
+Polymaps ist eine JavaScript library, die das Erstellen stark angepasster und dynamischer Karten ermöglicht. Als karthografische Ressourcen können OpenStreetMap, Google Maps, Bing und weitere Anbieter eingebunden werden.
+Die Anpassung und das Anzeigen zusätzlicher Informationen (Pfade, Lables, Statistiken, ...) auf der Karte erfolgt über SVG und GeoJson.
+Es eignet sich besonders Polymaps zusammen mit d3.js zu verwenden - eine weitere Javascript library, die das Erstellen datengetriebener Dokumente ermöglicht.
+Hinter Polymaps und d3.js stehen herraussragende Entwickler der Stanford Visualization Group und eine weitere Wartung der libraries ist sicher.
+
+* http://polymaps.org/
+* http://mbostock.github.com/d3/
+
+## Mitwirkende
+* Johannes Auer
+* Haykuhi Jaghinyan
+* Mirko Kiefer

docs/report.pdf

@@ -5,7 +5,7 @@
 %
 % This module implements A* to find the shortest path between two nodes
 % It makes use of the geodata module for accessing data.
-% The priority queue used by the algorithm is implemented in the priority_queue module.
+% The priority queue used by the algorithm is implemented in the astar_priority_queue module.
 
 -module(astar).
 -export([shortest_path/2, shortest_path_with_distances/2]).
@@ -27,7 +27,7 @@ shortest_path_internal(SourceID, TargetID) ->
   StartT = now(),
   Tab = ets:new(shortest_path, [set, public]),
   VisitedNodes = ets:new(visited_nodes, [set, public]),
-  Q1 = priority_queue:new(),
+  Q1 = astar_priority_queue:new(),
 
   ets:insert(Tab, {SourceID, {previous, undefined}, {distance, 0}}),
   Path = recurse_nodes(SourceID, TargetID, #state{tab=Tab, queue=Q1, visited_nodes=VisitedNodes}),
@@ -51,12 +51,12 @@ recurse_nodes(Target, Target, State) ->
 recurse_nodes(Node, Target, State=#state{tab=Tab, queue=Queue, visited_nodes=Visited}) ->
   visited(Node, true, Visited),
   OldQueueEntry = add_heuristic(get_distance(Node, Tab), Node, Target),
-  Q1 = priority_queue:remove({Node, OldQueueEntry}, Queue),
+  Q1 = astar_priority_queue:remove({Node, OldQueueEntry}, Queue),
   Neighbours = neighbours(Node),
   Q2 = update_distances(Node, Target, Neighbours, State#state{queue=Q1}),
   case gb_trees:size(Q2) of
     0 -> Tab;
-    _Any -> {ClosestNode, _Distance} = priority_queue:smallest(Q2),
+    _Any -> {ClosestNode, _Distance} = astar_priority_queue:smallest(Q2),
       recurse_nodes(ClosestNode, Target, State#state{queue=Q2})
   end.
 
@@ -81,8 +81,8 @@ recurse_neighbours([Neighbour|Rest], CurrentNode, CurrentDistance, Target, State
 
 % returns an updated version of the priority queue
 update_distance(Node, PreviousNode, OldDistance, NewDistance, Target, State) ->
-  Q1 = priority_queue:remove({Node, add_heuristic(OldDistance, Node, Target)}, State#state.queue),
-  Q2 = priority_queue:add({Node, add_heuristic(NewDistance, Node, Target)}, Q1),
+  Q1 = astar_priority_queue:remove({Node, add_heuristic(OldDistance, Node, Target)}, State#state.queue),
+  Q2 = astar_priority_queue:add({Node, add_heuristic(NewDistance, Node, Target)}, Q1),
   ets:insert(State#state.tab, {Node, {previous, PreviousNode}, {distance, NewDistance}}),
   Q2.
 

src/astar.erl

@@ -5,7 +5,7 @@
 %
 % This module provides a simple wrapper around erlang's gb_tree module to simplify usage as an efficient priority queue.
 
--module(priority_queue).
+-module(astar_priority_queue).
 
 -export([new/0, add/2, list/1, remove/2, remove_all/2, smallest/1]).
 

src/priority_queue.erl src/astar_priority_queue.erlsrc/priority_queue.erl renamed to src/astar_priority_queue.erl

@@ -0,0 +1,19 @@
+
+-module(astar_priority_queue_test).
+
+-include_lib("eunit/include/eunit.hrl").
+
+
+add_remove_get_smallest_test() ->
+  List = [{abc, 1}, {ab, 2}, {de, 4}],
+  Q1 = astar_priority_queue:add(List, gb_trees:empty()),
+  
+  ?assertEqual(List, astar_priority_queue:list(Q1)),
+  
+  ?assertEqual({abc, 1}, astar_priority_queue:smallest(Q1)),
+  
+  Q2 = astar_priority_queue:remove({abc, 1}, Q1),
+  ?assertEqual([{ab, 2}, {de, 4}], astar_priority_queue:list(Q2)),
+  
+  Q3 = astar_priority_queue:remove_all([{ab, 2}, {de, 4}], Q2),
+  ?assertEqual([], astar_priority_queue:list(Q3)).

src/astar_priority_queue_test.erl

@@ -13,9 +13,11 @@
 
 neighbours(NodeID) ->
   WayIds = store:node2wayids(NodeID),
-  Ways = lists:map(fun(WayID) -> #way{refs=Refs} = store:lookup_way(WayID),
-    Refs end, WayIds),
-  Neighbours = lists:flatten(lists:map(fun(Refs) -> neighbours(NodeID, Refs) end, Ways)),
+  Refs = lists:map(fun(WayID) ->
+    #way{refs=Refs} = store:lookup_way(WayID),
+    Refs
+  end, WayIds),
+  Neighbours = utils:flatten_once(Refs),
   NeighboursDetails = [{{node, Neighbour}, {distance, distance(NodeID, Neighbour)}} ||
     Neighbour <- Neighbours, store:lookup_node(Neighbour) =/= undefined],
   NeighboursDetails.
@@ -95,23 +97,4 @@ angle(A, B, C) ->
 coords(Node) ->
   {LatFloat, _} = string:to_float(Node#node.lat),
   {LonFloat, _} = string:to_float(Node#node.lon),
-  {LatFloat, LonFloat}.
-
-neighbours(Element, List) ->
-  case List of
-    [] -> Result = [];
-    [Element] -> Result = [];
-    [Element | Rest] -> [Next | _] = Rest, Result = [Next];
-    [First | Rest] -> Result = neighbours(Element, First, Rest)
-  end,
-  Result.
-  
-neighbours(Element, Last, List) ->
-  case List of
-    [] -> Result = [Last];
-    [Element | []] -> Result = [Last];
-    [Element | Rest] -> [Next | _] = Rest, Result = [Last, Next];
-    [_First | []] -> Result = [];
-    [First | Rest] -> Result = neighbours(Element, First, Rest)
-  end,
-  Result.
+  {LatFloat, LonFloat}.