Warum MBTiles in PMTiles umwandeln
MBTiles ist seit über zehn Jahren der Standardweg, um einen kompletten Satz von Kartenkacheln in einer einzigen Datei zu speichern, und Werkzeuge wie TileMill, Mapbox Studio und QGIS exportieren standardmäßig immer noch in dieses Format. Eine MBTiles-Datei ist jedoch eine SQLite-Datenbank. Das bedeutet: Um auch nur eine einzige Kachel daraus zu lesen, braucht man eine SQLite-Engine, egal ob es sich dabei um die eingebettete Bibliothek einer mobilen App oder um einen vollständigen Kachel-Server-Prozess handelt.
PMTiles beseitigt diese Anforderung vollständig. Es handelt sich um eine einzige flache Binärdatei, in der jede Kachel an einem bekannten Byte-Offset liegt und über ein kleines Verzeichnis adressiert wird, das ein Client einmal herunterladen und zwischenspeichern kann. Ein Browser oder eine Kartenbibliothek ruft einzelne Kacheln dann mit gewöhnlichen HTTP-Range-Requests ab. Das bedeutet, eine PMTiles-Datei kann direkt von einem statischen Datei-Host wie S3, Cloudflare R2 oder GitHub Pages ausgeliefert werden, ganz ohne Kachel-Server, ohne Datenbank und ohne jeglichen Backend-Prozess.
Dieses Tool verbindet die beiden Formate ohne Installation. Sie legen eine MBTiles-Datei ab, das Tool liest die Kacheltabelle direkt aus der eingebetteten SQLite-Datenbank aus, korrigiert den Koordinatenunterschied zwischen den beiden Formaten und setzt Byte für Byte eine gültige PMTiles-Datei zusammen, alles innerhalb Ihres Browser-Tabs.
So funktioniert die Umwandlung
Keine bestehende JavaScript- oder WebAssembly-Bibliothek kann eine PMTiles-Datei schreiben — das offizielle "pmtiles"-Paket ist nur ein Reader, gebaut zum Konsumieren von Archiven über HTTP, nicht zum Erzeugen davon. Dieser Konverter implementiert deshalb das PMTiles-v3-Binärformat direkt anhand der veröffentlichten Spezifikation: einen 127 Byte großen Header mit den Offsets, dem Zoombereich und den Grenzen der Datei, ein gzip-komprimiertes Verzeichnis der Kachelpositionen und die rohen Kachel-Bytes selbst.
Zwei Details sind für eine korrekte Umwandlung besonders wichtig. Erstens speichert MBTiles die Kachelzeilen in der "TMS"-Reihenfolge, gezählt von Süden aus, während PMTiles wie die meisten modernen Webkarten von Norden aus zählt. Der Konverter kehrt daher die Y-Koordinate jeder Kachel mit der Standardformel um, bevor er sie weiterverwendet. Zweitens adressiert PMTiles Kacheln nicht direkt über z/x/y — jede Kachel erhält stattdessen eine einzige ID aus einer Hilbert-Raumfüllkurve. Diese wird gewählt, weil sie geografisch benachbarte Kacheln in der entstehenden Datei nah beieinander hält, sodass ein Kartenviewer einen kleinen Bereich mit sehr wenigen HTTP-Requests laden kann. Jede Kachel wird nach dieser ID sortiert, in dieser Reihenfolge in die Datei geschrieben und in einem komprimierten Verzeichnis indexiert, in dem ein Reader per Binärsuche jede beliebige Kachel findet.
Die Ausgabe dieses Konverters wurde mit der offiziellen "pmtiles"-Reader-Bibliothek selbst überprüft, also demselben Code, den auch MapLibre GL zum Öffnen echter Archive verwendet. Dabei wurde bestätigt, dass jede geschriebene Kachel beim erneuten Einlesen byte-identisch zurückkommt, sowohl bei kleinen Kachelsätzen als auch bei Archiven, die groß genug sind, um die Verzeichnisaufteilung des Formats für sehr große Kachelzahlen zu benötigen.
Schritt-für-Schritt-Anleitung
Wählen Sie eine .mbtiles-Datei von Ihrem Computer aus, oder klicken Sie auf "Beispiel testen", um einen kleinen, spontan erzeugten synthetischen Kachelsatz zu laden.
Die Quellkacheln werden aus der MBTiles-Datei gelesen und auf der Karte dargestellt, sodass Sie vor der Umwandlung prüfen können, ob der richtige Kachelsatz geladen wurde.
Klicken Sie auf "In PMTiles umwandeln". Die Umwandlung läuft vollständig in Ihrem Browser ab: Jede Kachel wird gelesen, ihre Position auf der Hilbert-Kurve berechnet und die PMTiles-Datei zusammengesetzt.
Es erscheint eine Zusammenfassung: wie viele Kacheln umgewandelt wurden, der Zoombereich, das Kachelformat, die geografischen Grenzen und die Dateigröße der entstandenen PMTiles-Datei.
Klicken Sie auf "Download .pmtiles", um die fertige Datei auf Ihrem Computer zu speichern.
Anwendungsfälle aus der Praxis
Wo sich der Wechsel von MBTiles zu PMTiles tatsächlich lohnt.
- Kacheln auf einem statischen Datei-Host veröffentlichen. PMTiles lässt sich direkt von S3, Cloudflare R2, GitHub Pages oder jedem beliebigen einfachen Datei-Host über HTTP-Range-Requests ausliefern, ganz ohne laufenden Kachel-Server-Prozess — etwas, das eine MBTiles-SQLite-Datei allein nicht kann.
- Einen alten MBTiles-Export modernisieren. Vor Jahren aus TileMill, Mapbox Studio oder QGIS exportierte Kachelpakete liegen häufig noch als MBTiles vor. Die Umwandlung in PMTiles macht sie in aktuellen Karten-Stacks (MapLibre, Protomaps) nutzbar, ohne die Kacheln aus den Ausgangsdaten neu erzeugen zu müssen.
- Infrastruktur für ein kleines Kartenprojekt reduzieren. Eine einzige statische PMTiles-Datei macht es überflüssig, für einen überschaubaren, weitgehend statischen Kachelsatz einen eigenen Kachel-Server zu betreiben und zu pflegen. Das senkt Hosting-Kosten und die Zahl der beweglichen Teile bei kleineren Websites und internen Tools.
- Offline-Kartenpakete für Außendienst-Apps vorbereiten. Apps zur Felddatenerfassung und Offline-first-Kartenanwendungen lesen zunehmend PMTiles direkt aus dem lokalen Speicher. Wandelt man bestehende MBTiles-Basiskarten um, erhält man ein einheitliches Dateiformat für die Offline-App und jede Webkarte, die dasselbe Bildmaterial nutzt.
- Kachelsätze in einem cloud-nativen Format archivieren. Da PMTiles-Kacheln über Byte-Bereiche adressiert werden und keine Datenbankabfragen erfordern, lässt sich eine archivierte PMTiles-Datei auch Jahre später untersuchen, teilweise abrufen oder ausliefern, ohne dass eine bestimmte Datenbank-Engine installiert sein muss.
Häufig gestellte Fragen
Was ist PMTiles, und wie unterscheidet es sich von MBTiles?
Beide Formate packen einen kompletten Satz von Kartenkacheln in eine einzige Datei, aber MBTiles ist eine SQLite-Datenbank, für die selbst zum Lesen einer einzigen Kachel eine SQLite-Engine nötig ist. PMTiles ist eine einfache Binärdatei, die so entworfen wurde, dass ein Webserver (oder sogar ein statischer Datei-Host wie S3 oder GitHub Pages) einzelne Kacheln über gewöhnliche HTTP-Range-Requests ausliefern kann, ganz ohne laufenden Kachel-Server oder Datenbank.
Implementiert dieses Tool das PMTiles-Format tatsächlich selbst, oder greift es auf eine bestehende Bibliothek zurück?
Es implementiert das PMTiles-v3-Binärformat direkt: den 127 Byte großen Header, das gzip-komprimierte Kachelverzeichnis, das über eine Hilbert-Kurven-Kachel-ID adressiert wird, sowie den Datenbereich der Kacheln selbst. Nach unseren Recherchen beim Bau dieses Tools kann keine andere browserbasierte JavaScript-Bibliothek eine PMTiles-Datei schreiben — das offizielle "pmtiles"-Paket ist nur ein Reader —, weshalb dies direkt anhand der veröffentlichten Spezifikation umgesetzt werden musste.
Wie wurde tatsächlich überprüft, dass die Ausgabe korrekt ist?
Jede von diesem Tool erzeugte Datei wurde getestet, indem sie mit dem eigenen Reader des offiziellen "pmtiles"-npm-Pakets wieder eingelesen wurde — demselben Code, den MapLibre und andere Werkzeuge zum Öffnen echter PMTiles-Archive verwenden — und dabei bestätigt, dass jede Kachel byte-identisch zurückkommt. Das wurde sowohl für kleine Dateien als auch für Archive geprüft, die groß genug sind, um die "Leaf-Directory"-Aufteilung des Formats zu erfordern.
Warum sind die Y-Koordinaten für diese Umwandlung wichtig?
MBTiles speichert Kachelzeilen von oben nach unten in der "TMS"-Reihenfolge, gezählt von Süden aus. PMTiles zählt (wie die meisten modernen Webkarten) von Norden aus. Der Konverter kehrt die Y-Koordinate jeder Kachel mit der Standardformel um, y_new = 2^z − 1 − y_old, bevor er ihre Position in der Ausgabedatei berechnet, damit die Kacheln am richtigen Platz landen.
Funktioniert das sowohl für Vektorkacheln als auch für Rasterbilder?
Ja. Der Konverter liest das Feld "format" aus der Metadatentabelle von MBTiles, um PNG-, JPEG- und WebP-Rasterkacheln von PBF/MVT-Vektorkacheln zu unterscheiden, und setzt den passenden Kacheltyp im PMTiles-Header, damit nachgelagerte Werkzeuge wie MapLibre GL wissen, wie sie diese darstellen sollen.
Werden meine Metadaten (Name, Beschreibung, Quellenangabe, Vektorebenen) übernommen?
Ja. Name, Beschreibung, Quellenangabe und — bei Vektorkachelsätzen — das "vector_layers"-Schema aus der Metadatentabelle von MBTiles werden in den PMTiles-Metadatenblock kopiert, der als reines JSON innerhalb der Datei gespeichert wird.
Gibt es ein Größen- oder Kachelanzahl-Limit?
Uploads sind auf 100 MB begrenzt. Sehr große Kachelpakete (zehntausende Kacheln) benötigen mehr Verarbeitungszeit, da jede Kachel gelesen, anhand ihrer Position auf einer Hilbert-Kurve gehasht und wieder geschrieben wird, alles innerhalb Ihres Browser-Tabs.
Was passiert mit der Reihenfolge der Kacheln innerhalb der Datei?
Die Kacheln werden vor dem Schreiben nach einer Hilbert-Kurven-Kachel-ID sortiert, sodass Kacheln, die auf der Karte nah beieinanderliegen, auch in der Datei nah beieinanderliegen. Genau das ermöglicht es einem PMTiles-Reader, einen kleinen Kartenbereich mit sehr wenigen HTTP-Range-Requests abzurufen, statt einer Anfrage pro Kachel.
Wird meine MBTiles-Datei irgendwohin hochgeladen?
Nein. Das Einlesen der SQLite-Datenbank, die Berechnung der Kachelpositionen, das Komprimieren der Verzeichnisse und das Zusammensetzen der finalen PMTiles-Bytes geschehen alle lokal in Ihrem Browser, mithilfe eines WebAssembly-Builds von SQLite. Die Datei verlässt Ihr Gerät nie.
Die Umwandlung läuft vollständig in Ihrem Browser mithilfe eines WebAssembly-Builds von SQLite. Es wird niemals eine Datei auf einen Server hochgeladen. Kartenkacheln © OpenStreetMap-Mitwirkende.
Kartenkacheln © OpenStreetMap-Mitwirkende, gezeichnet mit Protomaps (gehostet von KONAKTIVE), mit CARTO als Ersatz.
