Details zum Kartenhandling

In diesem Dokument werden einige Details beschrieben, die erklären, wie AvNav mit Karten umgeht, welche Kartentypen es gibt, wie man neue Karten anlegen kann und wie man das Karten-Handling erweitern kann. Der erste Teil richtet sich an alle Nutzer und beschreibt ein wenig genauer, welche Karten genutzt werden können und wie man sie in AvNav installieren bzw. importieren oder konvertieren kann. Im zweiten Teil werden die Möglichkeiten beschrieben, wie man eigene Kartenquellen erzeugen kann und wie man das Kartenhandling in AvNav erweitern kann. Dieser Teil richtet sich an fortgeschrittene Nutzer.

Grundaufbau

Die Karten in AvNav sind entweder auf dem AvNav Server gespeichert oder können (je nach Typ) auch während der Nutzung direkt aus dem Internet geladen werden. Mit dem mapproxy-plugin gibt es eine Mischform, die Karten aus dem Internet lädt, anzeigt und gleichzeitig auf dem AvNav Server speichert. Unter Andorid ist der AvNav Server direkt in der App integriert.

Die Anzeige der Karten erfolgt immer in einem Browser - so wie die gesamte Bedienoberfläche von AvNav. Wie im Technischen Hintergrund beschrieben, werden dazu entsprechende JavaScript Bibliotheken genutzt.

Karten und Overlays

Typischerweise benötigt man für die Navigation nicht nur eine Karte sondern auf dieser Karte auch noch verschiedene Zusatz-Informationen. Neben den Informationen, die AvNav selbst bereitstellt - wie die Bootsposition, Kurslinien, die aktuelle Route oder AIS Ziele (siehe Navigationsseite) kann man auch sogenannte "Overlays" über die Karte legen.

Eine grundlegende Beschreibung findet sich in der Einführung. Unter Overlay Details findet man noch detaillierte Informationen dazu.

AvNav Kartentypen

AvNav kann einige Kartentypen direkt selbst verarbeiten. Man muss dazu nur eine der unterstützten Karten-Datei-Typen über

->->"Charts"->

zu AvNav hochladen. AvNav unterstützt die folgenden Kartentypen

Typ	Datei-Endung	Beschreibung
GEMF	.gemf	Ein für das Lesen optimiertes Kartenformat, das intern ein Verzeichnis der vorhandenen Kacheln enthält. Dieses Format wird auch vom AvNav Importer aus verschiedenen anderen Formaten erzeugt. Dieses Format kann intern mehrere Layer mit unterschiedlichen Auflösungen enthalten.
mbtiles	.mbtiles	Eine sqlite Datenbank, die neben den Kartenkacheln auch noch Metadaten enthält. Leider gibt es hier verschiedene Kodierungen der y Koordinate - die aber nicht immer korrekt bezeichnet werden. Daher kann man diese per Hand umstellen.
PMTiles	.pmtiles	Ein modernes binäres Dateiformat, das insbesondere für die Nutzung über einfache Webserver optimiert ist. Wenn man .pmtiles Dateien hochlädt, unterstützt AvNav zunächst nur Rasterkarten in diesem Format.Dazu wird die Information im Header der PMTiles Datei ausgewertet. Dort ist der Typ der Kartenkacheln vermerkt. AvNav erlaubt die Typen `Unknown(0), Png(2), Webp(4),Jpeg(3)` als Rastertypen. Auch Vektorkarten im PMTiles Format können verarbeitet werden. Das erfordert jedoch eine spezielle Kartendefinition mit dem entsprechenden Style-Dokument.
XML	.xml	Wie unten beschrieben kann man mit xml Dateien direkt eine Kartendefinition erstellen. Die XML Datei enthält dabei noch nicht die eigentlichen Kartendaten sonder nur einen Verweis auf diese - und Informationen zur Nutzung

Plugin Kartentypen

Plugins können im Prinzip beliebige weitere Kartentypen zu AvNav hinzufügen. Die folgenden Karten-Plugins sind für AvNav standardmäßig vorhanden.

Plugin	Kartentyp	Beschreibung
ochartsng	Vektor Karten	Das ochartsng Plugin dient zur Anzeige von o-charts Vektorkarten. Diese müssen im o-charts Shop gekauft werden und wie im Plugin beschrieben hochgeladen werde. Hinweis: Das Hochladen kann nicht auf der "Charts" Seite in AvNav erfolgen. Daneben können auch noch unverschlüsselte ENC (S57) nach einer Konvertierung angezeigt werden. Nur Linux und Android.
ocharts	Verktor- und Raster Karten	Das ocharts (legacy) Plugin dient eben falls zur Anzeige von Karten aus dem o-charts. Es kann auch Rasterkarten aus dem Shop nutzen. Auf neueren Systemen steht es nicht mehr zur Verfügung. Nur Linux
mapproxy	Online Karten	Das mapproxy Plugin erlaubt über eigene Definitionen den Zugriff auf online Kartendienste. Die Karten werden im AvNav Server zwischengespeichert und stehen damit auch ohne Internet zur Verfügung. Nur für Linux

Daneben gibt es u.U. noch weitere Plugins für andere Kartentypen. Siehe dazu auch die Liste der Plugins.

Verwalten von Karten

Die Verwaltung von Karten ist in der Einführung bereits beschrieben. Sie erfolgt über

{MM("MMchartspage")}

Im "Charts" Tab sind alle vorhandenen Karten aufgelistet und es können neue Karten hochgeladen werden (in den Formaten, die AvNav direkt versteht). Bei Klick auf eine Karte erhält man einen Dialog, mit dem man die Overlays bearbeiten kann, Karten ggf. herunterladen, Löschen oder direkt öffnen Kann. Plugin-Karten werden hier angezeigt, diese können hier jedoch normalerweise nicht gelöscht oder heruntergeladen werden.

Für MBTiles karten kann man hier das Schema der Karte umstellen. Dieses beschreibt, wie die y-Koordinate zählt.

Es gibt zwei Optionen

Name	Beschreibung
tms	y-Koordinate 0 ist Süden
zxy	y-Koordinate 0 ist Norden

Der Default ist tms. Leider gibt es oft MBTiles Dateien, die zxy nutzen aber das nicht in der Datei vermerken. Im Zweifel muss man daher probieren und das Schema ggf. umstellen, wenn die Karte falsch dargestellt wird. AvNav schreibt eine eigene Information in die MBTiles Datei, wenn man es im Dialog umstellt. Damit kann diese Datei dann auch auf anderen AvNav Systemen sofort korrekt genutzt werden.

Der mittlere Tab "Imports" zeigt Informationen über Karten, die in den Konverter von AvNav geladen wurden. Auf Android ist der Konverter nicht vorhanden.

Im Tab "Overlay Files" werden die Dateien aufgelistet, die man als Overlays zu Karten hinzufügen kann.

Es gibt ganz links noch einen Tab "Server" - der zeigt den Zustand der Server-Funktionen für das Kartenhandling.

Karten Konvertierung

Einige Karten können in AvNav erst nach einer Konvertierung angezeigt werden. Dabei werden diese Karten meist in .gemf Dateien umgewandelt, so das sie anschliessend effizient genutzt werden können. Plugins können zusätzliche Konverter installieren. Der Konverter ist nur für Linux und Windows verfügbar, nicht unter Android. Es können die folgenden Kartentypen umgewandelt werden:

Kartentyp	Datei-Endung	Beschreibung
BSB	.kap	Rasterkarten. Typischerweise viele einzelne Dateien. Bei Hochladen zum Konverter kann man ein Verzeichnis angeben, das wird dann zum Namen der erzeugten Karte. Bei vielen Karten ist der Prozeß langwierig - insbesondere auf einem RaspberryPi
BSB	.zip	Ein zip Archiv mit BSB Karten, die zu einer gemeinsamen Karte umgewandelt werden
S57 ENC	.zip	Mit plugin ochartsng. Die S57 ENC werden in ein OpenCPN spezifisches Binärformat (senc) umgewandelt und direkt dem ochartsng Plugin übergeben. Auf Linux und Windows. Ochartsng selbst läuft nicht auf Windows, aber der Konverter ist verfügbar und kann installiert werden. Damit können z.B. S57 Karten für Android dort konvertiert werden (unter Android ist der Konverter nicht vorhanden)

Um Karten zum Konverter hochzuladen nutzt man

->->"Imports"->

Der Konverter wird nach gewisser Zeit die hochgeladenen Dateien erkennen (bei Einzeldateien wird noch etwas gewartet um weitere Uploads zu ermöglichen), danch startet die Konvertierung.

Wenn man das rot markierte Icon klickt, öffnet sich ein Dialog um das Log einzusehen, den Import zu löschen, zu restarten oder auch die konvertierten Karten noch einmal herunterzuladen.

Kartenquellen

Download von fertigen Rasterkarten (z.B. von OpenSeamap , NOAA) - mbtiles
Download mit dem Mobile Atlas Creator.
Kaufen von Karten bei o-charts und Nutzung mit dem ochartsng Plugin
Download von S57 und Konvertierung/Nutzung mit dem ochartsng plugin
Nutzung von Karten vom SignalK Chart Provider (wenn die SignalK-Integration aktiv ist).
Karten von freenauticalchart.net.
Inland ENC vom WSV (Elwis) - Konvertierung/Nutzung mit dem ochartsng plugin

Hinweis: ENC werden oft als viele einzelne ZIP Dateien bereitgestellt. Wenn man möchte, das diese in AvNav als eine gemeinsame Karte konvertiert und angezeigt werden, sollte man die ZIP-Archive vor dem Hochladen zu AvNav in ein gemeinsames Archiv zusammenpacken.

Daneben finden sich im Internet noch viele weitere Kartenquellen, die ggf. in AvNav nutzbare Karten bereitstellen.

Erweiterte Kartendefinitionen

Einführung

Um eine Karte zu nutzen, benötigt AvNav eine sogenannte Kartendefinition. Für die eigenen Kartentypen erzeugt AvNav diese selbständig. Für andere Karten kann das durch den Nutzer oder durch ein Plugin erfolgen.

Eine solche Definition beschreibt, aus welchen Schichten (Layern) diese Karte besteht, welchen Typ diese Layer haben und wo die Daten dafür herkommen. Siehe auch Technischer Hintergrund.

Der einfachste Fall einer solchen Definition in Form einer XML Datei für den online Zugriff auf OpenStreetMap Karten kann z.B. so aussehen:

<?xml version="1.0" encoding="UTF-8" ?>
 <TileMap 
    type="zxy"
    href="http://a.tile.openstreetmap.org"
    minzoom="4"
    maxzoom="20">
    <BoundingBox minlon="-20" minlat="10" maxlon="30" maxlat="70"/>
 </TileMap>

Man kann diese Definition in eine XMLDatei (z.B. SimpleOSM.xml) schreiben, sie über

->->"Charts"->

in AvNav hochladen und die OpenStreetMaps Karte steht unter dem Name SimpleOSM.xml zur Anzeige bereit.

Dieses Beispiel enthält genau einen Kartenlayer, die Kartenkacheln kommen vom Server unter http://a.tile.openstreetmap.org - und sie haben die Default-Größe von 256x256 Pixeln.

Über "profile" wird der Typ des Layers ausgewählt - dieser bestimmt, wie aus der angegebenen URL die URLs für die einzelnen Kartenkacheln gebildet werden - und wie diese dargestellt werden.

Die Beschreibung einer Kartendefinition ist entweder eine XML Darstellung wie im Beispiel oder ein JavaScript/JSON Objekt. Das obige Beispiel als JSON Objekt:

[
    {
        "profile": "zxy",
        "href": "http://a.tile.openstreetmap.org",
        "minzoom": "4",
        "maxzoom": "20",
        "boundingbox": {
            "minlon": "-20",
            "minlat": "10",
            "maxlon": "30",
            "maxlat": "70"
        }
    }
]

Bei den Parametern ist die Groß-/Kleinschreibung irrelevant.

Einbringen von Kartendefinitionen

Kartendefinitionen können auf verschiedene Art in AvNav eingebracht werden.

XML Datei

Wie im Beispiel beschrieben können Kartendefinitionen als XML Datei zu AvNav hochgeladen werden.

plugin.json

Plugins können eine Datei plugin.json mitbringen. Diese muss ein Objekt mit verschiedenen Eigenschaften enthalten. Unter dem Namen "charts" kann hier eine Liste von Kartendefinitionen registriert werden.

{
  "charts": [
    {
      "layers": [
        {
          "url": "chart/base.pmtiles",
          "name": "main",
          "minzoom": 6,
          "maxzoom": 18,
          "profile": "PMTiles"
        }
      ],
      "name": "test-base",
      "icon": "compass.svg"
    }
  ]
}

Relative Angaben bei url oder icon beziehen sich auf den Speicherort der plugin.json Datei.

Plugin Python Code

Nur für Windows und Linux/Raspberry. Im Plugin Python API gibt es die Funktion registerChartProvider.

Der dort übergebene Callback wird gerufen, wenn AvNav die Liste seiner Karten ermitteln möchte. Er muss eine Liste von Kartendefinitionen zurückgeben wie unter plugin.json beschrieben.

Dynamische Layerliste

Für die Definitionen per plugin.json oder python kann die Kartendefinition auch in zwei Schritten erzeugt werden.

Das kann insbesondere Sinn machen, wenn die Karten durch einen separaten Server ausserhalb von AvNav bereitgestellt werden.

Wenn die Kartendefinition noch keine "layers" enthält, versucht AvNav beim Öffnen der Karte die finale Kartendefinition zu laden. Diese Definition muss wieder eine Kartendefinition im XML Format sein. AvNav erwartet in der Definition eine URL, von der dieses XML Dokument geladen werden kann.

Wenn die Kartendefinition einen Parameter overviewUrl enthält wird diese genutzt, sonst wird der Parameter url genutzt und /avnav.xml angefügt. Eine solche zweistufige Kartendefinition kann z.B. so aussehen:

{
    "charts": [
      {
        "name": "test-chart",
        "icon": "compass.svg"
        "url": "http://$HOST:8002/charts/testchart"
      }
    ]
}

In diesem Beispiel wird angenommen, das ein Server für die Karten auf dem gleichen Computer wie AvNav läuft und unter Port 8082 seine Daten bereitstellt. Die Kartendefinition für die Karte "test-chart" wird dann über die URL http://nn.nn.nn.nn:8082/charts/testchart/avnav.xml abgerufen. Die Kartenlayer im XML Dokument müssen dann nicht mehr unbedingt eine URL enthalten - es wird dann die Basis-URL http://nn.nn.nn.nn:8082/charts/testchart genutzt.

Layer Typen

AvNav hat eine Reihe von eingebauten Karten-Layer Typen. Diese erwarten die Kartendaten jeweils in einem bestimmten Format und laden sie über bestimmte URLs. Plugins oder Nutzer-JavaScript können weitere Layer Typen ergänzen. Diese Layer erzeugen intern jeweils ein Kartenlayer für openlayers oder MapLibre. Die Implementierung der Kartenlayer findet man in chartlayers.js

Parameter

Paremeter, die von mehreren Layern verstanden werden:

url (alternativ kann "href" genutzt werden)

Dieser kann weggelassen werden, wenn die Kartendaten unter der gleichen Basis-URL wie die Kartenbeschreibung gefunden werden. Für Details siehe die Java Script Interface Beschreibung.
minzoom - Integer, der minimale Zoomlevel
maxzoom - Integer, der maximale Zoomlevel

boundingbox - Objekt

der Bereich der Karte mit den Parametern minlat, maxlat, minlon, maxlon

"boundingbox": {
    "minlon": "-180",
    "minlat": "-66.477366283",
    "maxlon": "179.955",
    "maxlat": "85.05112878",
    "title": "bounding"
},

layerzoomboundings - Objekt oder Array Dieser Wert beschreibt für die verschiedenen Zoom-Stufen, welche x/y Bereiche vorhanden sind. Beispiel:

"layerzoomboundings": [
        {
            "zoom": "2",
            "boundingbox": {
                "minx": "0",
                "maxx": "3",
                "miny": "0",
                "maxy": "2"
            }
        },
        {
            "zoom": "3",
            "boundingbox": {
                "minx": "1",
                "maxx": "7",
                "miny": "0",
                "maxy": "4"
            }
        },
]

Die boundingbox Einträge bei jedem zoom Level können auch ein Array von Objekten sein, falls es mehrere nicht zusammenhängende Bereiche gibt. Dieser Parameter wird meist nur bei Karten erzeugt, die AvNav selbst kennt. Der Vorteil der Angabe ist, das nicht versucht wird, Kacheln zu laden, die es nicht gibt.

upzoom

wenn keine Kacheln für einen Zoom Level verfügbar sind, versuche Kacheln von kleineren Zoom Leveln zu nehmen - maximal bis herunter zu zoom - upzoom

Layer xzy

Das ist der default Layer, der auch genutzt wird. Die URLs werden nach dem OSM Schema erzeugt. https://xxxxxx/zoom/x/y.png. y started mit 0 im Norden. Die Kachelgröße ist 256x256.

Parameter

Name	Optional	Beschreibung
profile	ja	zxy oder leer
url	siehe oben	Die Basisurl für die Kartendaten. `zoom/y/x.png` werden für jede Kachel ergänzt. Alternativ kann die URL Platzhalter `{z} {x} {y}` enthalten, dann werden die Werte dort eingefügt.
minzoom	ja
maxzoom	ja
boundingbox	ja
upzoom	ja
layerzoomboundings	ja

Layer tms

Dieser Layer ist fast identisch zum Layer zxy - nur die y Koordinate ist invertiert. 0 ist im Süden. Die Parameter sind ebenfalls identisch zum Typ zxy, der Parameter type muss auf tms gesetzt werden.

Layer wms

Dieser Layer kann genutzt werden, um Kartenkacheln von einem Web Map Service zu laden. Ein solcher Service adressiert nicht direkt die Kacheln, sondern es werden die Eck-Koordinaten angegeben und die Größe des zu ladenden Bildes. Meist gehören auch noch weitere Parameter dazu. Der Layer erzeugt GetMap Requests an den konfigurierten Service.

Parameter

Name	Optional	Beschreibung
profile	nein	wms
url	siehe oben	Die angegebene URL wird mit einer Reihe von Parametern ergänzt.
minzoom	ja
maxzoom	ja
boundingbox	ja
upzoom	ja
layerzoomboundings	ja
projection	ja	Die Projektion, die der Service nutzt. Default `EPSG:4326`
wmsparameter	ja	Ein Array von Objekten name, value `[{"name":"TRANSPARENT","value":"TRUE"}]`. Diese werden als Parameter an die URL angefügt.
layermapping	ja	Ein Array von Objekten zooms,layers, das es erlaubt je nach Zoom unterschiedliche WMS Layer abzufragen. Zooms und Layers können jeweils durch , getrennte Werte enthalten. Beispiel: `[{"zooms":"1,2,3,4,5","layers":"Overview,Special"},{"zooms":"6,7,8","layers":"Details"}]`

Die finale URL für die Abfrage des WMS wird dann durch die bei "url"angegebene URL sowie eine Liste von Parametern gebildet.

Parameter	Quelle
SERVICE	fix: `WMS`
REQUEST	fix: `GetMap`
FORMAT	fix: `image/png`
SRS	Parameter `projection`
WIDTH	fix: Kachelgröße 256
HEIGHT	fix: Kachelgröße 256
BBOX	die berechnete Boundingbox für die Kachel
LAYERS	wenn der Parameter `layermapping` angegeben war, wird dieser Parameter in Abhängigkeit vom Zoom versorgt, sonst nicht
XXX...	alle name,value Paare, die bei `wmsparameter` angegeben wurden

Layer encrypt

Dieser Layer ist ein Speziallayer für das ochartsng und das ocharts Plugin. Als "profile" werden die Werte 'encrypted-zxy','encrypted-zxy-mercator' akzeptiert.

Layer PMTiles

Dieser Layer kann für PMTiles Raster Quellen genutzt werden.

Parameter

Name	Optional	Beschreibung
profile	nein	`PMTiles`
url	siehe oben	Die Basisurl für die Kartendaten
minzoom	ja
maxzoom	ja

Eine Beispiel für die Nutzung von PM Raster Quellen:

<?xml version="1.0" encoding="UTF-8" ?>
 <TileMap 
   profile="PMTiles"
   href="https://pmtiles.io/stamen_toner(raster)CC-BY+ODbL_z3.pmtiles" 
    minzoom="2"
    maxzoom="4">
 </TileMap>

Layer mapLibreVector

Dieser Layer kann für Vektorkarten genutzt werden. Diese werden mit MapLibre dargestellt.

Vektorkarten benötigen neben den Kartendaten im Allgemeinen noch mindestens 3 weitere Datentypen:

ein "style" Dokument - im Allgemeinen eine .json Datei. Diese beschreibt im Detail, wie die Daten dargestellt werden sollen. Für genauere Informationen siehe die Beschreibung bei MapLibre.
die auf der Karte anzuzeigenden Symbole (sprites). Der Link dazu ist im "style" Dokument enthalten.
die Fonts für die Textdarstellung. Auch dazu sind die Links im "style" Dokument enthalten.

Die darzustellenden Kartendaten (tiles) werden normalerweise durch Links auf ein oder mehrere TileJSON APIs beschrieben. Die Kacheln (tiles) selbst werden für Vektorkarten meist im pbf Format genutzt. Sie können dabei von einem Server geladen werden oder z.B. aus einer PMTiles Datei.

Neben diesen Grunddaten kann man für diesen Karten-Layer noch weitere KOnfigurationen angeben, die dann direkt in Paremeter für MapLibre umgesetzt werden.

Parameter

Name	Optional	Beschreibung
profile	nein	`maplibreVector` oder `maplibre``
style	nein	siehe unten
maplibre	ja	ein Objekt, das direkt als Eigenschaften an die MapLibre Map übergeben wird
useProxy	ja	Wenn Vektordaten von einem Server geladen werden erfordert das korrekte CORS Einstellungen auf diesem Server. Sonst verweigert der Browser das Laden der Daten. Da man diese Server nicht immer unter Kontrolle hat, gibt es die Möglichkeiten, die Anfragen über den AvNav Server zu leiten. Da die AvNav Webseite ja auch von diesem Server kam, tritt dabei das CORS Problem nicht auf. Das funktioniert natürlich nur, wenn der AvNav Server den Kartenserver auch direkt erreichen kann

Der style Parameter kann auf verschiedene Arten angegeben werden:

als Parameter style oder urloder styleUrl
als Wert style im Parameter maplibre

Der Wert des Parameters kann dabei ein String sein - in diesem Fall wird er als eine URL interpretiert und das Style Dokument wird von dieser URL geladen. Alternativ kann der Wert auch ein Objekt sein - in diesem Falle wird der Wert direkt als style Parameter an MapLibre übergeben.

Als Erweiterung zu MapLibre kann das Style-Dokument auch ein yaml Dokument sein. Das kann durch die Nutzung von Ankern und anderen YAML Funktionen die Arbeit beim Schreiben von solchen Dokumenten erleichtern. Nach dem Laden wird das Dokument in JSON umgewandelt und dann an MapLibre übergeben.

Erweiterungen (eigene Karten-Layer)

Experten

Das Erstellen eigener Kartenlayer erfordert JavaScript Know How und auch eine gewisse Einarbeitung in das Handling der Kartenbibliotheken. Daher wird eine solche Erweiterung meist in Plugins eingebaut.

Eigene Kartenlayer erweitern die vorhandenen Kartenlayer. Damit kann man z.B. vor der Nutzung noch mit dem Kartenserver kommunizieren (z.B. einen GetCapabilities Request an einen WMS Server schicken, um die verfügbaren Layer zu ermitteln ), man kann Nutzer-Präferenzen setzen oder z.B. Karteninformationen abrufen und aufbereiten für die FeatureListe.

Registrierung

Im JavaScript API von AvNav (das für Plugins und Nutzer-JavaScript-Code zur Verfügung steht) gibt es dazu die Funktion registerUserMapLayer.

Mit dieser Funktion registriert man ein neues Profil, das dann in Kartendefinitionen verwendet werden kann.

Die Funktion hat die folgenden Parameter:

Name	Typ	Beschreibung
baseName	String	Der Kartenlayer, der erweitert werden soll. Einer der Profilnamen wie unter Layer Typen angegeben.
name	String	Der Profilname für den neuen Layer. Wenn die Funktion in user.mjs aufgerufen wird, wird intern dem Namen noch `user_` vorangestellt, wenn sie in einem Plugin gerufen wird, wird `plugin_` vorangestellt. In einer Kartendefinition muss man also `"profile":"user-myprofile"` schreiben.
callback	Funktion	Eine Funktion, die aufgerufen wird, sobald ein Kartenlayer mit diesem Profil angelegt werden soll. Für die Beschreibung siehe unten

Callback

Im API sieht man die Definition der Callback Funktion, die beim Erzeugen eines Kartenlayers aufgerufen wird.

Der context Parameter erlaubt die Speicherung von Werten, die spezifisch für diesen Aufruf sind. Er wird auch in allen weiteren Callbacks übergeben.

Die Funktion darf async sein oder auch eine Promise zurückgeben.

Der Rückgabewert der Funktion unterscheidet sich, je nachdem ob man einen Vektorlayer oder einen Rasterlayer erweitert.

Das Resultat kann in beiden Fällen modifizierte Parameter (options) zurückgeben - diese ersetzen dann die in der Kartenkonfiguration angegebenen. Ausserdem können verschiedene Callback-Funktionen angegeben werden.

Callback	Typ	Beschreibung
finalizeFunction	alle	wird gerufen, bevor die Karte geschlossen wird
sequenceFunction	alle	wird in regelmässigen Abständen gerufen um zu prüfen, ob sich die Karte geändert hat und neu geladen werden muss. Sobald sich der zurückgegebene String verändert, wird die Karte neu geladen
loadCallback	Vektor	wird nach dem Laden der MapLibre Map gerufen und erlaub den direkten Zugriff auf das Map-Objekt
featureListFormatter	Vektor	Wird gerufen, wenn der Nutzer auf die Karte klickt. Als Parameter wird eine Liste der Vektor-Objekte im Klick-Bereich übergeben. Siehe unten
createTileUrlFunction	Raster	Die Rasterlayer erzeugen die URL zum Laden einer Kachel mit einer URLFunction. Dieser callback kann genutzt werden, um eine eigene URLFunction zurückzugeben. Damit können z.B. weitere Parameter eingefügt werden, die der Server benötigt
tileLoadFunction	Raster	Diese Funktion ermöglicht es, das Laden der Serverdaten in ein JavaScript Image zu beeinflussen.

Eine besonders interessante Möglichkeit ist die Aufbereitung von Vektor-Kartendaten für den Nutzer mit der featureListFormatter Funktion.

Die übergebene Liste enhält Objekte die alle Properties des jeweiligen Open Layer Features("get" Methode) enthalten. Auuserdem sind die folgenden Eigenschaften vorhanden:

Name	Beschreibung
`_gtype`	Geometrie-Typ (String)
`_lon`	Longitude
`_lat`	Latitude
`vectorTileFeature`	das originale MapLibre Feature

Diese Objekte sind durch parsen der GeoJSON Darstellung von MapLibre entstanden - und damit ähnlich den Features, die in einem GeoJSON Overlay entstehen.

Die Rückgabe des Formatters muss ein Array mit Objekten vom Typ FeatureInfoType sein.

Die als Resultat zurückgegebenen Objekte werden in einem Feature List Dialog angezeigt. Für ein gutes Nutzererlebnis sollte die Rückgabe nur ein einziges Objekt enthalten mit einer akkumulierten Darstellung der wichtigsten Features (z.B. Typ, Top-Zeichen und Licht einer Tonne).

Eine aufbereitete Liste mit den Informationen aller Objekte sollte HTML formatiert im Wert htmlInfo des Objektes hinterlegt werden (oder über link als URL abrufbar sein).

Siehe auch FeatureFormatter.

Ein Bespiel findet sich im Plugin für freenauticalcharts.

Technischer Hintergrund

Damit Karten in AvNav im Browser angezeigt werden können, müssen sie in einem „Kachelformat“ vorliegen. Das ist das Format, das durch Dienste wie OpenStreetMaps oder GoogleMaps benutzt wird. Eine Kartenkachel ist meist 256x256 Pixel gross. Die Welt wird dabei auf eine ebene Fläche projiziert (das kann man sich wie einen Papierzylinder vorstellen, der senkrecht steht und am Äquator um die Erde gewickelt wird). Jeder Punkt mit seinen Koordinaten (Länge/Breite) wird dann auf diesen Zylinder projiziert. Wie man das macht, welche Einheiten in der Projektion verwendet werden und ob die Erde als Kugel oder Ellipsoid mit verschiedenen Parametern modelliert wird, beschreiben die verschiedenen Projektionen. Die WebApp benutzt die sogenannte Google-Mercator-Projektion (die Erde wird dabei als Kugel betrachtet) - mit dem EPSG Code 900913. Die Einheiten auf dem Papier sind dabei Meter (die man natürlich in die entsprechenden Koordinaten umrechnen kann). Karten in einem anderen Format (z.B. WGS84 – Erde als Ellipsoid, immer in Grad) müssen daher ggf. reprojiziert werden.

Die gesamte Projektionsfläche wird bei der Google-Projektion in Kacheln unterteilt. Der Zoom Level gibt an, in wieviele Kacheln die Fläche unterteilt wird. Zoom Level 0 bedeutet: die gesamte Erde (von -85° bis +85° Breite – darüber ist die Projektion nicht definiert) auf einer Kachel von 256x256 Pixel. Mit jedem weiteren Zoom Level wird feiner unterteilt: Zoom Level 1: 2x2 Kacheln, 2: 4x4 Kacheln usw. Für uns reichen die interessanten Zoom Level von ca. 7 bis 18..19. Das bedeutet (Level 19) 2^19x2^19 Kacheln.

Zur Darstellung wird die Library openlayers verwendet. Diese lädt die entsprechenden Kartenkacheln je nach Zoom Level vom Server und zeigt sie an. OpenStreetMaps verwendet typischerweise diese Library. Es ist dabei möglich innerhalb einer Karte mehrere sogenannte Layer (Schichten) übereinander zu legen - auf diesem können z.B. unterschiedliche Auflösungen verwendet werden - oder auch in einem Layer die Basis-Karten und in einem anderen Layer die Seezeichen. Zusätzlich können auch Kartenlayer mit MapLibre genutzt werden. Damit lassen sich z.B. Verktorkarten darstellen. Das erfordert jedoch typischerweise zusätzliche Daten und erfordert damit spezielle Kartendefinitionen oder Plugins.

Man kann sich leicht vorstellen, dass bei hohen Zoom Levels schnell große Datenmengen zusammenkommen. Daher müssen wir für unsere Kartenkacheln ähnlich vorgehen, wie es auch bei den Papierkarten ist: für Übersichten ein kleinerer Zoom Level, Detailkarten größer und z.B. Hafenpläne dann mit Level 18 oder 19 (60cm/pixel bzw. 30cm/pixel). Um damit arbeiten zu können, werden die verschiedenen Detailgrade dann in Layern (Schichten) übereinandergelegt. Wenn es für ein Gebiet einen Layer mit besserem (größerem) Zoom Level gibt, wird dieser angezeigt - wenn nicht, der mit der geringeren Auflösung (ggf. noch vergrössert). Um unsere Anzeigegeräte nicht zu überlasten, kann man typisch mit 3-5 Kartenlayern arbeiten (je nach Gerät...).