Wegwichtel/docs/agents/GPX-Aufzeichnung.md

GPX und Wegaufzeichnung

Stationen und Weg getrennt speichern

• Stationen mit Koordinaten stehen als wpt unmittelbar unter gpx.
• Der Schalter „Meinen Weg aufnehmen“ ist beim Start und beim Öffnen eines Entwurfs aus. Einschalten fragt sofort den Standort ab, danach alle zwei Minuten. Bei noch nicht gespeicherten Entwürfen beginnt die Aufnahme nach dem ersten Speichern. Schließen, Abbrechen, Rückkehr zur Streckenliste oder Wechsel der Strecke beendet die Aufzeichnung und schaltet sie aus. Speichern innerhalb derselben Sitzung hebt Pause oder bewusstes Stoppen nicht auf.
• Die sichtbaren Schaltflächen erlauben Pausieren, Fortsetzen und Beenden. Beim Löschen des Entwurfs endet die Aufzeichnung ebenfalls.
• Tatsächliche Positionen stehen als trk/trkseg/trkpt mit Zeitstempel und, falls vorhanden, Höhe in der Datei des Entwurfs.
• Ohne Standort entsteht eine Erweiterung wegwichtel:gpsGap mit Zeitstempel. Eine Station ohne Standort steht als wegwichtel:pendingWaypoint in den Erweiterungen. Es werden keine Koordinaten wie 0,0 erfunden. Leere GPX- wpt oder trkpt wären ungültig, daher werden Erweiterungen verwendet.

Die Aufzeichnung speichert immer die neueste Fassung des Entwurfs, damit gleichzeitige Änderungen an Stationen erhalten bleiben. Auch eine manuelle Bearbeitung ergänzt die neueste Aufzeichnung und bewahrt inzwischen hinzugekommene Positionen. Speicherfehler pausieren die Aufzeichnung und zeigen einen Hinweis.

Später Koordinaten ergänzen

Entwürfe und Stationen dürfen ohne GPS erstellt und gespeichert werden. In der Streckenbearbeitung können unter „Orte auf dem Weg ergänzen“ fehlende Positionen ergänzt, vorhandene geändert und weitere hinzugefügt werden. Das Zielkreuz an jedem Wegpunkt fragt frische GPS-Koordinaten ab und füllt nur dessen Felder. Es startet keine Aufnahme; die Änderung muss gespeichert werden. Verspätete Antworten nach dem Wechseln oder Schließen werden verworfen. Breiten- und Längengrad müssen gemeinsam angegeben werden oder beide leer bleiben. Stationen haben eigene Felder unter „Ort ergänzen“.

Die Serverdatenbank erlaubt NULL in pois.lat und pois.lon. Die Tabelle route_points entfällt. Routenpunkte, Start und Mittelpunkt, Weglänge, Höhengewinn und Punktzahl werden aus der gespeicherten GPX-Datei gelesen beziehungsweise berechnet. Die Änderung ist in database/schema.sql enthalten; eine bestehende Datenbank bekommt sie nicht allein durch das Kopieren des Codes. Das Projekt verwendet beim Deployment die vereinbarte Neuerstellung der Datenbank, keine automatische Migration.

SQLite enthält weiterhin Verwaltungseinträge, Freigaben sowie Stations- und Medienangaben. Von den berechneten Routenwerten bleiben dort ausschließlich min_lat, min_lon, max_lat und max_lon als Suchwerte erhalten. Die Näheresuche verwendet diese Grenzen zur Vorauswahl und berechnet anschließend den Abstand zum Start aus der GPX-Datei. Anlegen, Ersetzen, Anhängen und Änderungen an Stationen aktualisieren die Grenzen. Ohne Koordinaten bleiben alle vier leer.

Die Startprüfung erwartet dasselbe Schema einschließlich der optionalen Stationskoordinaten, lehnt die entfernte Tabelle und Routenspalten ab und prüft die Suchgrenzen gegen die GPX-Dateien. Ein zusätzlicher Test führt die Prüfung in einem getrennten Prozess mit einer echten temporären Datenbank und Dateien aus. Damit wird der Fall einer vorhandenen Datenbank auch beim normalen Coverage-Lauf geprüft.

Normalisierung auf dem Server

Beim Einreichen oder Ersetzen einer GPX-Datei normalisiert der Node-Dienst den aufgezeichneten Weg und gültige Stations-Wegpunkte zu rte/rtept. Bereits vorhandene Routenpunkte bilden anstelle von Trackpunkten den Grundverlauf. Aufeinanderfolgende Trackpunkte innerhalb des eingestellten Abstands werden zusammengefasst. Der erste Punkt bleibt der Vertreter; der nächste wird erst übernommen, wenn er weiter entfernt liegt. So werden kleine Schwankungen während einer Pause nicht fortlaufend zur Weglänge addiert.

Nach dem Vereinfachen des Tracks werden alle gültigen wpt ergänzt. Sie werden nicht durch den Clusterabstand entfernt. Ihre Reihenfolge in der Datei bleibt erhalten; der Einfügeort im verbleibenden Weg wird anhand der kleinsten zusätzlichen Weglänge gewählt. Übereinstimmende Orte werden zusammengeführt. Eine Strecke mit nur Stationen erhält einen Weg in Stationsreihenfolge. Weglänge, Routenpunktzahl und Suchgrenzen beziehen sich auf den gemeinsamen Weg.

Aus Stationen ergänzte Routenpunkte tragen in ihren GPX-Erweiterungen die Kennung wegwichtel:waypointRoutePoint. Dadurch lassen sich bei erneuter Normalisierung bzw. Verschieben/Löschen einer Station alte ergänzte Anker entfernen und anhand der aktuellen wpt neu berechnen. Ursprüngliche Wegpunkte im aufgezeichneten Verlauf bleiben erhalten. Beim Anhängen einer anderen Strecke wird deren berechneter Weg als zusätzlicher Verlauf übernommen. Wiederholte Normalisierung darf keine zusätzlichen Stationsanker erzeugen.

GPX_CLUSTER_METERS in .env steuert den Abstand, standardmäßig 20 Meter. Das Verfahren ist eine geometrische Vereinfachung ohne externen Routingdienst. Es berechnet keine Wege auf einer Straßenkarte. GPS-Lücken werden bei der Routenberechnung übersprungen; zwischen gültigen Nachbarpunkten entsteht eine direkte Verbindung. Die Lücken bleiben für spätere Bearbeitung als Erweiterungen erhalten. Gibt es weder gültige Wegpositionen noch Stationen mit Koordinaten, bleiben Weglänge und Punktzahl bei 0 Metern und 0 Punkten; Stationen bleiben trotzdem gespeichert.

Die gespeicherte Serverdatei enthält den normalisierten Weg. Änderungen an Stationen synchronisieren die wpt und die noch unvollständigen Stationen in dieser Datei. GPX verwendet unverändert den Namespace http://www.topografix.com/GPX/1/1; das ist eine Kennung, kein Netzwerkabruf.

Anzeige beim Abspielen

Zwei Pfeile zeigen gleichzeitig die Richtung:

• zum nächsten Routenpunkt, ohne Entfernungsangabe;
• zur nächsten noch offenen Station mit Koordinaten, mit Metern.

Bei einem lokalen Entwurf mit ausschließlich Stationen fehlt vor dem Hochladen die Wegführung. Nach dem Hochladen verbindet der berechnete Weg die Stationen. Stationen ohne Koordinaten lösen keine Standort-Erkennung aus. Während einer Pause werden die Pfeile verborgen.

Grenzen und Prüfung

Die Aufzeichnung läuft nur im geöffneten App-Fenster. Neuladen beendet sie; bereits gespeicherte Positionen bleiben erhalten. Browser und Betriebssystem können Zeitgeber und Standort-Abfragen im Hintergrund oder bei gesperrtem Bildschirm verzögern. Ein verlässlicher Hintergrunddienst wird nicht zugesichert. Bei verweigerter Standort-Erlaubnis bleiben die Einträge leer und bearbeitbar.

Die Tests prüfen Aufzeichnung, Pause/Fortsetzen/Ende, verspätete GPS-Antworten, Speicherfehler, GPS-Lücken, manuelle Ergänzungen, getrennte Pfeile, Servernormalisierung sowie Stationen ohne Koordinaten über die API.