Folgen Sie GpsWandern.de auch per Atom-Feed:

RSS
Gpswandern.de Gastautorenprogramm

TrackViewer-API - Referenz ~ Das Nachschlagewerk für alle Optionen der API

TrackViewer-API - Referenz

Das Nachschlagewerk für alle Optionen der API

Diese Programmier-Referenz wendet sich an den Webmaster, der die TrackViewer-API auf seinen eigenen Seiten einsetzen will. Hier gibt es alle Optionen und Funktionen der API in einer Übersicht aufgelistet.

Für Anwender des interaktiven Trackviewers oder einer einfachen Trackanzeige sind die hier aufgeführten Programmieroptionen nicht nutzbar.

Kartenfenster mit TrackViewer-API erzeugt (Screenshot)

Kartenfenster mit TrackViewer-API erzeugt (Screenshot)

Constructor

Constructor Parameter Beschreibung Beispiel
TrackViewer keine erzeugt ein neues TrackViewer Objekt Tv = new TrackViewer;

Methoden

Methoden Parameter Beschreibung Beispiel
request() keine ruft die Verarbeitung auf. Zuvor sollten alle Optionen gesetzt sein. Die Methode wartet von sich aus auf DOM-ready. Tv.request();

Optionen

Optionen Typ Beschreibung Beispiel
    Alle Parameter sind optional, falls nicht anders angegeben!  
url string URL der GPX-Datei. Dieser Parameter ist unbedingt erforderlich. Er kann absolut ("http://...", bzw. "https://...") oder relativ zur aufrufenden HTML-Datei angegeben werden. Tv.url = "http://helmutkarger.de/download/tvapi/beispiel.gpx";
oder
Tv.url = "meineWanderung.gpx";
mapDiv string Id des DIV-Elements, das die Karte aufnehmen soll. (Fehlt dieser Parameter oder ist das DIV im HTML-Code nicht vorhanden, so wird keine Karte ausgegeben) Tv.mapDiv = "karte";
eleProfDiv string Id des DIV-Elements, das das Höhenprofil aufnehmen soll. Tv.eleProfDiv = "hoehenprofil";
eleLargeTabDiv string Id des DIV-Elements für eine große Höhendatentabelle. Tv.eleLargeTabDiv = "hoehentabelle";
eleSmallTabDiv string Id des DIV-Elements für eine kleine Höhendatentabelle. Tv.eleSmallTabDiv = "hoetabklein";
selectedMaps array of strings Auswahl der gewünschten Karten. Mehr siehe Kartenseite. Tv.selectedMaps = ["OpenStreetMap.de", "OpenStreetMap.fr Humanitaire", "OpenTopoMap", "ÖPNVKarte"];
mapType string Auswahl der initial angezeigten Karte. Nur nötig, falls eine andere als die erste der selectedMaps gewünscht wird. Tv.mapType = "OpenTopoMap";
thunderforestApiKey
hereApiKey
mapboxApiKey
maptilerApiKey
geoapifyApiKey
jawgApiKey		 string Eingabemöglichkeit für erworbene API-Keys von verschiedenen Anbietern. Mehr siehe Kartenseite. Tv.thunderforestApiKey = "12345678901234567890";
maxZoom integer Reduzierung des maximalen Zoomlevels (default ist 22). Tv.maxZoom = 18;
lineArrows boolean Pfeile an die Linien zeichnen (default = true). Tv.lineArrows = false;
lineColor string oder array of strings Linienfarbe bestimmen.
Angabe einer Einzelfarbe oder einer Farbreihe. (Liste gültiger Farbangaben)		 Tv.lineColor = "#FF9F00";
oder
Tv.lineColor = ["#FF9F00","red", "green", "blue"]
overwriteGpxColor boolean Farbangaben der GPX-Datei mit Farbe(n) aus lineColor überschreiben (default = false). Tv.overwriteGpxColor = true;
scrollWheelZoom boolean Zoom in der Karte mit dem Mausrad erlauben (default = true). Tv.scrollWheelZoom = false;
eleProfWidth integer Breite des Höhenprofils (Image) in Pixel. Tv.eleProfWidth = 570;
eleProfHeight integer Höhe des Höhenprofils (Image) in Pixel. Tv.eleProfHeight = 170;
eleProfRouteStyle string Bei mehreren Routen/Tracks kann die Anordnung im Höhenprofil auf verschiedene Arten erfolgen:
serial: die zweite Route beginnt am Ende der ersten,
parallel: alle Routen beginnen am Anfang oder
auto (default): das Programm entscheidet das anhand der Routenführung automatisch.		 Tv.eleProfRouteStyle = "parallel";
eleProfXsections integer Richtwert für die Anzahl der X-Achsenunterteilungen. Tv.eleProfXsections = 10;
eleProfYsections integer Richtwert für die Anzahl der Y-Achsenunterteilungen. Tv.eleProfYsections = 5;
eleProfMarginLeft integer Linker Rand des Höhenprofils in Pixel (Raum für die Achsenbeschriftung). Tv.eleProfMarginLeft = 50;
eleProfMarginBottom integer Unterer Rand des Höhenprofils in Pixel (Raum für die Achsenbeschriftung). Tv.eleProfMarginBottom = 20;
eleProfMarginRight integer Rechter Rand des Höhenprofils in Pixel. Tv.eleProfMarginRight = 20;
eleProfMarginTop integer Oberer Rand des Höhenprofils in Pixel. Tv.eleProfMarginTop = 20;
eleProfMarkerLength integer Länge der Achsmarkierungen in Pixel. Tv.eleProfMarkerLength = 7;
eleProfAxisWidth integer Linienbreite der Achsen im Höhenprofil in Pixel. Tv.eleProfAxisWidth = 2;
eleProfAxisColor string Farbe der Achsen (nur hex RGB-Code mit voranstehendem #). Tv.eleProfAxisColor = "#000000";
eleProfGridColor string Gitternetzfarbe des Höhenprofils (nur hex RGB-Code mit voranstehendem #). Tv.eleProfGridColor = "#fefefe";
eleDataUpDownThreshold integer Schwellwert in Meter bei der Berechnung der Auf- und Abstiegsmeter. Auf- und Abwärtsbewegungen unterhalb dieses Schwellwerts werden bei der Aufsummierung ignoriert. 5m sind sind ein guter Wert für Wanderungen. Tv.eleDataUpDownThreshold = 5;

Daten

Daten Typ Beschreibung Beispiel
version string die aktuelle Version der TrackViewer-API. alert (Tv.version);
ergibt etwas wie "5/0/0"
local.allMaps object Datenobjekt aller in der TrackViewer-API vorbereiteten Karten mit deren Url, maxNativeZoom Information und angepasstem maxZoom. function userExit1(obj) {
 console.log(obj.local.allMaps);
}
local.map object enthält das Kartenobjekt, das damit (per Userexit) direkt angesprochen werden kann. function userExit4(obj) {
 obj.local.map.setZoom(5);
}
host.status string Rückmeldung der serverseitigen Verarbeitung. Der String ist im Erfolgsfall leer und enthält andernfalls eine Fehlermeldung. function userExit2(obj) {
 alert (obj.host.status);
}
host.urlreal string Diese Rückmeldung der serverseitigen Verarbeitung enthält die reale absolute URL der GPX-Datei, die möglicherweise aus einer relativen URL abgeleitet ist. function userExit2(obj) {
 alert (obj.host.urlreal);
}
data.structure array die Struktur der einzelnen Tracks (Routen) zueinander (hintereinander, parallel), wie sie von eleProfRouteStyle = "auto" erkannt wird. function userExit4(obj) {
 alert (obj.data.structure);
}
ergibt etwas wie [[0,1],2], was soviel bedeutet wie Track 0 und 1 verlaufen hintereinander und Track 2 parallel zu beiden.
data.all array Direktzugriff auf die Höhendaten. Array[0] enthält dabei die Summen über alle Routen. Bei eleProfRouteStyle = "auto" können auch Zwischensummen entstehen, die im Array an die Daten der Einzelrouten angehängt werden. Jedes Arrayelement hat folgende Datenfelder:
Feld Typ Beschreibung
name string Name der Route
color string Linienfarbe in hex-RGB
wpts integer Anzahl der Wegpunkte
km real Streckenlänge in km
start integer Höhe des Startpunkts
dest integer Höhe des Zielpunkts
max integer höchste gemessene Höhe
min integer niedrigste gemessene Höhe
diff integer Höhendifferenz
up integer Höhenmeter im Aufstieg
down integer Höhenmeter im Abstieg
function userExit4(obj) {
 alert('Die Gesamtlänge beträgt '
  +obj.data.all[0].km+ 'km und
  der Anstieg der ersten Route '
  +obj.data.all[1].up+ 'm.');
}

Userexits

Userexits sind Funktionen, die an bestimmten Stellen aus der Verarbeitung der TrackViewer-API (also "request()") heraus aufgerufen werden, sofern diese Funktionen existieren. Als Parameter wird jeweils das TrackViewer-Objekt übergeben.
Syntax:
function userExit4(obj) {
 // mach irgendwas mit obj
}

Userexits Beschreibung
userExit1(obj) request() wurde aufgerufen und abgewartet bis DOM komplett geladen ist. obj.local.allMaps (alle Kartenabrufinformationen) steht ab hier zur Verfügung. Die serverseitige Verarbeitung wurde noch nicht angestoßen.
userExit2(obj) Die serverseitige Verarbeitung wurde beendet aber noch nicht geprüft.
userExit3(obj) Die serverseitige Verarbeitung wurde beendet und es ist dabei kein Fehler aufgetreten. Die Anzeige von Karte oder Höhenprofil wurde jedoch noch nicht gestartet, so dass die Daten noch geändert werden können.
userExit4(obj) Alle angeforderten Anzeigen der TrackViewer-API (Karte, Höhenprofil, kleine und große Datentabelle) sind abgeschlossen. Die TrackViewer-API ist quasi fertig und es können eigene zusätzliche Programmschritte folgen.

Farben

Die Spezifikation des GPX-Datenformats sieht an sich keine Farbinformationen vor. Von Garmin existiert jedoch eine Erweiterung (extension) die folgende Farben als sogenannte Display-Colors definiert:

Black
DarkRed
DarkGreen
DarkYellow
DarkBlue
DarkMagenta
DarkCyan
LightGray
DarkGray
Red
Green
Yellow
Blue
Magenta
Cyan
White
Transparent

Die TrackViewer-API wertet diese Farbangaben aus, wenn sie zum einen direkt in GPX-Dateien vorkommen oder zum anderen als Farbinformationen per lineColor angegeben werden. Das Format für Farbangaben in GPX-Dateien sieht am Beispiel eines Tracks folgendermaßen aus:
..
<trk>
 <name>ActiveLog</name>
 <extensions>
  <gpxx:TrackExtension xmlns:gpxx="http://www.garmin.com/xmlschemas/GpxExtensions/v3">
   <gpxx:DisplayColor>DarkRed</gpxx:DisplayColor>
  </gpxx:TrackExtension>
 </extensions>
  <trkseg>
  <trkpt lat="48.1388828" lon="11.5648227">
   <ele>913</ele>
  </trkpt>
  ..
 </trkseg>
</trk>
..
Über diesen "Garmin-Standard" hinaus erlaubt die TrackViewer-API auch Farbangaben im hexadezimalen RGB-Format also zum Beispiel "#FF00FF" für magenta. Das ergibt eine Farbauswahl aus über 18 Millionen Farben (True Color). Bitte beachten Sie aber, dass GPS-Geräte und andere Programme wie zum Beispiel MapSource diese Farbenvielfalt nicht darstellen können.

Für Farbangaben für das Höhenprofil (eleProfAxisColor und eleProfGridColor) können die "Garmin-Farbdefinitionen" nicht verwendet werden. Hier ist nur das hexadezimale RGB-Format erlaubt.

Hilfe

Weitere Anleitungsseiten zum Themenkomplex TrackViewer-API finden Sie hier:

Stand: Dezember 2020