Note Autor: Wolfram Eberius
Version: 0.0.1
Datum: 01.04.2023

Preface

Der KulturpfadService ist eine Software, die zur Planung der digitalen Form der Kulturpfade verwendet werden kann. Er bietet die Möglichkeit aus einer Liste von Geokoordinaten einen Pfad zu errechnen.

Hierfür wird ein csv-Dokument mit Punkten übergeben. Hieraus wird eine Linien erstellt, die in Form von geojson Objekten ausgeliefert werden.

Die Software ist als eigenständiger Service gedacht, die es erlaubt, die notwendigen Daten für die Bereitstellung einer Oberfläche ohne Backend zu generieren.

Der Service enthält eine einfache Weboberfläche, die die Planung erleichtert.

Die Berechnung der Route erfolgt mit Hilfe von graphhopper.

1. Interfaces

Es werden folgende Interfaces unterstützt

1.1. poi

get /serivce/poi/<key>
accept application/json
returns geojson

Diese Schnittstelle liefert alle gespeicherten Points Of Interest (POI).

1.2. route

get /serivce/route/<key>
accept application/json
returns geojson

Diese Schnittstelle liefert die Route aus den übergebenen Points of Interest (POI).

1.3. data

get /serivce/data/<key>
accept application/json
returns json

Diese Schnittstelle gibt eine json mit den wichtigsten Informationen zum Routing zurück.

1.4. gpx

get /serivce/gpx/<key>
accept application/json
returns gpx

Diese Schnittstelle gibt die Route als GPX Daten zurück.

2. Daten

Es werden unterschiedliche Arten von Daten unterschieden:

  • OpenStreetMap Daten

  • Daten für das Routing

  • Daten zu Abschnitten und POI

2.1. OpenStreetMap Daten

Die Applikation benutzt die Routing-Engine von Graphhopper. Hierfür ist es notwendig die passenden OSM-Daten zur Verfügung zu stellen. Sie werden vom Server der Geofabrik bezogen. Das Kopieren erfolgt während des Bauens der Anwendung. Mit dem initialen Aufruf von mvn clean install wird ein Datenabzug heruntergeladen, der in der pom.xml definiert ist.

Beispiel Regierungsbezirk Köln
<download-osm.fromFile>europe/germany/nordrhein-westfalen/koeln-regbez-latest.osm.pbf</download-osm.fromFile>

Im angegebenen Beispiel werden die Daten für den Regierungsbezirk Köln heruntergeladen

Beispiel für Hessen
<download-osm.fromFile>europe/germany/hessen-latest.osm.pbf</download-osm.fromFile>

Im Beispiel für Hessen wird ein Abzug für das Bundesland Hessen heruntergeladen.

Wenn die Routing-Daten aktualisiert werden sollen, kann dies mit Hilfe von mvn clean install oder mvn clean integration-test erfolgen. mvn clean sorgt dabei dafür, dass das Arbeitsverzeichnis gelöscht wird. mvn install sorgt unter anderem dafür, dass frische Daten von der Geofabrik heruntergeladen werden.

Auf der Seite geofabrik.de/europe/germany [7] findet sich einen Auflistung, welche Daten von der Geofabrik bezogen werden können.

2.2. Daten für das Routing

Daten werden in Form von csv-Dateien eingelesen. Diese Dateien werden im resources Verzeichnis hinterlegt. Die Daten sollte entsprechend der id aufgebaut sein:

Dateiname
b03-t06.csv

Die Struktur besteht aus vier Spalten:

id

eindeutige id; z.B. 'b03-t06-01-0'

name

Name des Punktes; 'null' wenn Stützpunkt

lat

Breitengrad; z.B. '51'

lng

Längengrad; z.B. '7'

Jeder Datensatz sollte durch die id eindeutig identifizierbar sein. Sie sollte im Bezug auf die Kulturdaten folgendermaßen aufgebaut werden:

<bezirk>-<tour>-<nr>-<punkt>

Wichtig ist hier, dass die Werte innerhalb der ID in der weiteren Verarbeitung verwendet werden. Dafür ist es notwendig, dass die Werte durch - von einander getrennt werden.

Table 1. Bedeutung der id

bezirk

Bezirk des Kulturpfades: z.B. Lindental: b03

tour

Nummer der Tour; z.B. Tour 1: t01

nr

Nummer des Ankerpunktes; p01 für Ankerpunkt, s01 für Stützpunkt

punkt

6.1 - Ankerpunkt; 0 - Stützpunkt
Beispieldatensatz
koeln-innenstadt-p01-1;Heinzelmännchenbrunnen;50.940007983370705;6.957310070072043
koeln-innenstadt-u02-2;Unter Goldschmied;50.93915927;6.95810884
koeln-innenstadt-u03-3;Theo Burauen Platz;50.93895138;6.95841998
koeln-innenstadt-s04-2;Theo Burauen Platz;50.93895138;6.95841998
koeln-innenstadt-u05-4;Römische Wasserleitung;50.93910674660413;6.958303544859174
koeln-innenstadt-u06-5;Laurenzgittergäßchen;50.93912378;6.95863724
koeln-innenstadt-u07-6;Praetorium;50.93902067;6.95895642
koeln-innenstadt-u08-7;Rathaus;50.93799641;6.95930243
koeln-innenstadt-u09-8;Altermarkt;50.93859475;6.96001858
koeln-innenstadt-s10-3;Fischmarkt;50.93828375;6.96217239
koeln-innenstadt-u10-9;Hänneschen-Theater am Eisenmarkt;50.93708368;6.96196318
koeln-innenstadt-s11-4;Altermarkt;50.93668478;6.96149647
koeln-innenstadt-u11-10;Reiterdenkmal Friedrich Wilhelm;50.93625883;6.96068645
koeln-innenstadt-u12-11;Gürzenich;50.93651913;6.95844412
koeln-innenstadt-s03-5;Gürzenich;50.93623516;6.95820272
koeln-innenstadt-s03-10;null;50.93627742;6.95804179
koeln-innenstadt-u12-12;Marsplatz, Marspfortengasse;50.93759583;6.95928901
koeln-innenstadt-u13-13;Wallraf-Richartz Museum;50.93739976;6.95843875
koeln-innenstadt-u14-14;Farina;50.93770062;6.95809275
koeln-innenstadt-u15-15;Gülichplatz;50.93757723;6.95807129
koeln-innenstadt-s15-6;Gülichplatz;50.93757723;6.95807129
koeln-innenstadt-u16-16;Fastnachtsbrunnen;50.93757385;6.95795327

Generell sollten die Sehenswürdigkeiten verwendet werden, um die Route zu berechnen. Es werden alle Sehenswürdigkeiten berücksichtigt, die in der csv-Datei mit 'p' markiert sind. Dabei kommt es immer häufiger zu Abweichungen zwischen Sehenswürdigkeit und Route, weil z.B. mehrere Sehenswürdigkeiten in unmittelbarer Nähe zueinander liegen, oder eine Sehenswürdigkeit nicht direkt an der Route liegen soll oder kann,

Durch die Markierung der Sehenswürdigkeit mit 'u' in der csv-Datei, wird die entsprechende Sehenswürdigkeit nicht mehr ins Routing einbezogen. Zusätzlich ist es möglich unsichtbare Punkte durch die Markierung 's' in der csv-Datei zu definieren. Im Ergebnis wird ggf eine Route mit nicht sehr aussagefähigen Entfernungen aber richtiger gesamter Entfernung und Laufzeit ermittelt.

In Zukunft soll das Konzept folgendermaßen geändert werden:

p

Punkte, die einen POI kennzeichnen

sie werden in das Routing einbezogen, aber auch auf der Oberfläche anzeigen

s

Punkte, die die Strecke kennzeichnen

sie werden nur angezeigt, wenn der Name nicht 'null' ist

u

Punkte, die einen POI kennzeichnen

sie werden nicht in das Routing einbezogen aber auf der Oberfläche angezeigt. Dies sollte der Normalfall für die Kennzeichnung von POI sein.

  • p: Punkte, die einen POI kennzeichnen; sie werden in das Routing einbezogen, aber auch auf der Oberfläche anzeigen

  • s: Punkte, die die Strecke kennzeichnen; sie werden nur angezeigt, wenn der Name nicht 'null' ist

  • u: Punkte, die einen POI kennzeichnen; sie werden nicht in das Routing einbezogen aber auf der Oberfläche angezeigt. Dies sollte der Normalfall für die Kennzeichnung von POI sein.

Durch die Konzentration auf 'u' und 's' kann die Strecke vom POI getrennt werden. Die Berücksichtigung von 'p' erlaubt es rückwärtskompatibel zu bleiben. Eine eigene Nummerierung von 'u' und 's' Punkten bedeutet auch, dass de Darstellung auf der Oberfläche und die Darstellung der Route unabhängig voneinander nummeriert werden können.

Generell sollen nur Points of Interest miteinander verbunden werden. Dies sind die Ankerpunkte der Route. Es ist aber ggf notwendig Stützpunkte hinzuzufügen, die die Route so anpassen, dass nicht der direkte Weg errechnet wird. Ankerpunkte sind dadurch gekennzeichnet, dass die id mit der Ordnungszahl des Kulturpfades endet, während Stützpunkte dadurch gekennzeichnet sind, dass sie den Prefix mit dem Ankerpunkt teilen, aber die Nummer mit dem 's' verbunden sind.

Es werden allerdings auch Ankerlose Punkte untersützt. Sie sind dann notwendig, wenn ein POI nicht mit in das Routing einbezogen werden soll. Ankerlose Punkte sind durch die Zeichenkombination "-u" gekennzeichnet. Bsp.: b09-t01-u01-0.1

Weiterhin wird die zweite Spalte, die für das Feld name steht, mit dem Wert null gefüllt.

Ankerpunkt und zwei Stützpunkte, ein ankerloser Punkt
b03-t06-p01-6.1;Pauliplatz;50.93808;6.89794
b03-t06-s01-0;null;50.939027;6.894951
b03-t06-s02-0;null;50.936174;6.894329
b03-t06-u01-7.1;Platz;50.92808;6.88794

3. UI

Die Anwendung wird mit einer Web-Oberfläche geliefert, die es erlaubt den aktuell zu entwickelnden Pfad anzuzeigen.

Die Webanwendung ist durch folgende Eigenschaften gekennzeichnet:

  • Der Überblick zeigt den Weg und die Anzahl der Sehenswürdigkeiten entlang einer Route. Der Verlauf des Weges entspricht bestmöglich der ursprünglichen Streckenführung des Kulturpfades.

  • Die Kartenansicht zeigt Details entlang des Pfades an. Die Sehenswürdigkeiten werden durch rote Marker mit ihren Nummern angezeigt.

  • Ein modaler Dialog zeigt Informationen zu den Sehenswürdigkeiten. Die Texte sind den Heften entnommen, die für die Kulturpfade veröffentlicht wurden. Ein Foto illustriert den Eintrag.

  • Die Route wird mit einem für dieses Projekt entwickelten Routingsystem berechnet. Dadurch ist es möglich, nicht nur die Länge der Strecke, sondern auch die benötigte Zeit anzuzeigen.

  • Die Informationen im Dialog zu den Sehenswürdigkeiten enthalten den Hinweis auf die Quelle. Weitere Informationen sind verlinkt.

  • Jedem Kulturpfad ist ein Text vorangestellt, der die Besonderheiten der Route betont. Diese Texte finden sich im Menüpunkt ‚About‘.

  • Es können unterschiedliche Sprachen angezeigt werden. Eigennamen werden nicht übersetzt. Jede weitere Sprache ist mit zusätzlichem redaktionellen Aufwand verbunden.

  • Das Locate Tool ermöglicht es den Standort an den Browser zu übermitteln. Die aktuelle Position wird als blauer Punkt der auf der Karte angezeigt.

  • Mit Aufruf der Seite werden alle Daten in den Browser übertragen. Die Verarbeitung erfolgt auf dem Smartphone. Es werden keine Daten über Personen, ihr Nutzungsverhalten oder ihre Position erhoben oder gespeichert.

  • Jeder Kulturpfad hat seine eigene Seite. Die Pfade des Bezirks können über den Menüpunkt ‚About/ Links‘ gefunden werden.

  • Die Seite ‚Über das Projekt‘ beschreibt die Zusammenhänge. Hier ist es möglich Kontakt zum Entwicklungsteam aufzunehmen.

4. Test

Es werden Unit-Tests und Integrationstests unterschieden. Unit-Tests umfassen die Tests, die keinerlei Backend benötigen. Integrationstests benötigen ein eingebundenes graphhopper. Es sind keine Oberflächen Tests vorgesehen.

Die Unit-Tests können mit folgendem Kommando aufgerufen werden:

mvn test

Die Integrations-Tests werden mit folgendem Kommando aufgerufen:

mvn integration-test

Hierbei ist zu beachten, dass ein Abzug von OpenStreetMap im Classpath zur Verfügung stehen muss. Sollte die entsprechende *.pbf Datei nicht vorhanden sein, wird sie automatisch heruntergeladen. Dadurch kann es zu langen Laufzeiten kommen, wenn die Intergrationstest mit folgendem Befehl aufgerufen werden:

mvn clean integration-test

Durch den Parameter clean wird das temporäre target Verzeichnis, und damit auch die *.pbf Datei gelöscht.

4.1. maven

Zu Unterscheidung von Junit-Tests und Integrationstests wird das maven-surefire-plugin eingestetzt. Während bei für den 'normalen' Testdurchlauf, also die Junit-Tests, alle Testklassen ausgeschlossen werden, die auf IntegrationTest oder ApplicationTests enden, werden diese explizit in der integration-test phase angesprochen.

keine Integrationstests
<plugin>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>2.22.2</version>
    <configuration>
        <excludes>
            <exclude>**/*IntegrationTest</exclude>
            <exclude>**/*ApplicationTests</exclude>
        </excludes>
    </configuration>
</plugin>
Integrationstests nur in der phase integration-test
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>2.22.2</version>
    <executions>
        <execution>
            <phase>integration-test</phase>
            <goals>
                <goal>test</goal>
            </goals>
            <configuration>
                <excludes>
                    <exclude>none</exclude>
                </excludes>
                <includes>
                    <include>**/*IntegrationTest</include>
                    <include>**/*ApplicationTests</include>
                </includes>
            </configuration>
        </execution>
    </executions>
</plugin>

5. Dokumentation

Die Dokumentation wird in adoc unter /src/main/asciidoc fortgeführt. Dadurch kann die Dokumentation sowohl in das pdf-Format umgewandelt werden, als auch in das html-Format. Für das Rendern des html-Codes, wird folgender Befehl auf der Kommandozeile ausgeführt:

Kommando zum Rendern der Dokumentation
mvn prepare-package

Um die erstellten html-Daten in das docs Verzeichnis zu kopieren, wird folgender Befehl auf der Kommandozeile ausgeführt:

Kommando zum kopieren der Dokumentation
mvn process-resources

Wenn die so erstellten html-Dateien mit eingecheckt werden, wird aktuell die Dokumentation unter KulturpfadeService zur Verfügung gestellt.

Bibliography