Perché convertire MBTiles in PMTiles
Da oltre dieci anni MBTiles è il modo standard per raccogliere un intero insieme di tile mappa in un unico file, e strumenti come TileMill, Mapbox Studio e QGIS lo esportano ancora come formato predefinito. Ma un file MBTiles è un database SQLite, e questo significa che leggere anche una sola tile richiede un motore SQLite, che si tratti della libreria integrata in un'app mobile o di un intero processo di tile-serving in esecuzione su un server.
PMTiles elimina del tutto questa necessità. È un unico file binario piatto in cui ogni tile si trova a un offset di byte noto, indicizzato tramite una piccola directory che il client può scaricare una sola volta e mettere in cache. Un browser o una libreria per mappe recupera poi le singole tile usando normali richieste HTTP a intervalli (range request), il che significa che un file PMTiles può essere servito direttamente da un semplice hosting statico come S3, Cloudflare R2 o GitHub Pages, senza alcun tile server, database o processo di backend.
Questo strumento collega i due formati senza bisogno di installare nulla. Carica un file MBTiles e lo strumento legge direttamente la tabella delle tile dal database SQLite incorporato, corregge la differenza di coordinate tra i due formati e costruisce un file PMTiles valido byte per byte, tutto dentro la scheda del tuo browser.
Come funziona la conversione
Nessuna libreria JavaScript o WebAssembly esistente è in grado di scrivere un file PMTiles: il pacchetto ufficiale "pmtiles" è solo un lettore, pensato per consumare archivi via HTTP, non per produrli. Per questo il convertitore implementa direttamente il formato binario PMTiles v3 seguendo la sua specifica pubblicata: un header di 127 byte che contiene gli offset del file, l'intervallo di zoom e i limiti geografici; una directory compressa con gzip delle posizioni delle tile; e i byte grezzi delle tile stesse.
Due dettagli sono fondamentali per una conversione corretta. Primo: MBTiles memorizza le righe delle tile nell'ordine "TMS", contando da sud, mentre PMTiles conta da nord come la maggior parte delle mappe web moderne; il convertitore inverte la coordinata Y di ogni tile con la formula standard prima di usarla. Secondo: PMTiles non indirizza le tile direttamente tramite z/x/y, ma assegna a ciascuna tile un unico ID ricavato da una curva di Hilbert, una curva che riempie lo spazio scelta apposta perché mantiene vicine, nel file risultante, le tile geograficamente vicine tra loro, così un visualizzatore di mappe può caricare una piccola area con pochissime richieste HTTP. Ogni tile viene ordinata secondo questo ID, scritta nel file in quell'ordine e indicizzata in una directory compressa che un lettore consulta con una ricerca binaria per trovare qualsiasi tile.
L'output di questo convertitore è stato verificato usando la libreria di lettura ufficiale "pmtiles", lo stesso codice che MapLibre GL usa per aprire archivi reali, confermando che ogni tile scritta torna identica byte per byte quando viene riletta, sia per tileset piccoli sia per archivi abbastanza grandi da richiedere la suddivisione della directory prevista dal formato per conteggi di tile molto elevati.
Guida passo per passo
Scegli un file .mbtiles dal tuo computer, oppure clicca su "Prova un esempio" per caricare un piccolo tileset sintetico generato al momento.
Le tile sorgente vengono lette dal file MBTiles e disegnate sulla mappa, così puoi verificare che sia stato caricato il tileset giusto prima di convertirlo.
Clicca su "Converti in PMTiles". La conversione avviene interamente nel browser: lettura di ogni tile, calcolo della sua posizione sulla curva di Hilbert e costruzione del file PMTiles.
Compare un riepilogo: quante tile sono state convertite, l'intervallo di zoom, il formato delle tile, i limiti geografici e la dimensione del file PMTiles risultante.
Clicca su "Scarica .pmtiles" per salvare il file completato sul tuo computer.
Casi d'uso reali
I casi in cui passare da MBTiles a PMTiles porta un vantaggio concreto.
- Pubblicare tile su un hosting statico. PMTiles può essere servito direttamente da S3, Cloudflare R2, GitHub Pages o qualsiasi hosting di file semplice usando richieste HTTP a intervalli, senza alcun tile server in esecuzione: una cosa che un file MBTiles basato su SQLite non può fare da solo.
- Aggiornare un vecchio export MBTiles. I pacchetti di tile esportati anni fa da TileMill, Mapbox Studio o QGIS sono spesso ancora in formato MBTiles. Convertirli in PMTiles li rende utilizzabili negli stack per mappe attuali (MapLibre, Protomaps) senza dover rigenerare le tile dai dati sorgente.
- Ridurre l'infrastruttura di un piccolo progetto di mappe. Un unico file PMTiles statico elimina la necessità di gestire un tile server dedicato solo per servire un tileset modesto e per lo più statico, riducendo i costi di hosting e le componenti da mantenere per siti piccoli e strumenti interni.
- Preparare pacchetti di mappe offline per app da campo. Le app di raccolta dati sul campo e le mappe pensate per funzionare offline leggono sempre più spesso PMTiles direttamente dallo storage locale. Convertire le basemap MBTiles esistenti significa avere un unico formato di file sia per l'app offline sia per qualsiasi mappa web che condivide le stesse immagini.
- Archiviare tileset in un formato adatto al cloud. Poiché le tile PMTiles sono indirizzate per intervallo di byte anziché richiedere query su un database, un file PMTiles archiviato può essere ispezionato, scaricato parzialmente o servito anche anni dopo senza bisogno di installare alcun motore di database specifico.
Domande frequenti
Cos'è PMTiles e in cosa differisce da MBTiles?
Entrambi raccolgono un intero insieme di tile mappa in un unico file, ma MBTiles è un database SQLite, e leggere anche una sola tile richiede un motore SQLite. PMTiles è un semplice file binario progettato in modo che un server web (o persino un hosting statico come S3 o GitHub Pages) possa servire le singole tile con normali richieste HTTP a intervalli, senza alcun tile server o database in esecuzione.
Questo strumento implementa davvero il formato PMTiles, o si appoggia a qualche libreria esistente?
Implementa direttamente il formato binario PMTiles v3: l'header di 127 byte, la directory delle tile compressa con gzip e indirizzata tramite un ID basato sulla curva di Hilbert, e la sezione dei dati delle tile. Per quanto abbiamo potuto verificare durante lo sviluppo, nessun'altra libreria JavaScript per browser è in grado di scrivere un file PMTiles: il pacchetto ufficiale "pmtiles" è solo un lettore, quindi è stato necessario costruire tutto a partire dalla specifica pubblicata.
Come è stata verificata la correttezza dell'output?
Ogni file prodotto da questo strumento è stato testato rileggendolo con il lettore della libreria ufficiale npm "pmtiles", lo stesso codice usato da MapLibre e da altri strumenti per aprire archivi PMTiles reali, confermando che ogni tile torna identica byte per byte. Il controllo è stato fatto sia su file piccoli sia su archivi abbastanza grandi da richiedere la suddivisione in "leaf directory" prevista dal formato.
Perché le coordinate Y contano in questa conversione?
MBTiles memorizza le righe delle tile dall'alto verso il basso nell'ordine "TMS", contando da sud. PMTiles (come la maggior parte delle mappe web moderne) conta da nord. Il convertitore inverte la coordinata Y di ogni tile con la formula standard, y_new = 2^z − 1 − y_old, prima di calcolarne la posizione nel file di output, così le tile finiscono nel posto giusto.
Funziona anche con le tile vettoriali, oltre alle immagini raster?
Sì. Il convertitore legge il campo "format" dalla tabella dei metadati di MBTiles per distinguere le tile raster PNG, JPEG e WebP dalle tile vettoriali PBF/MVT, e imposta il tipo di tile corretto nell'header PMTiles in modo che strumenti a valle come MapLibre GL sappiano come renderizzarle.
I miei metadati (nome, descrizione, attribuzione, layer vettoriali) verranno mantenuti?
Sì. Il nome, la descrizione, l'attribuzione e, per i tileset vettoriali, lo schema "vector_layers" presi dalla tabella dei metadati di MBTiles vengono copiati nel blocco dei metadati di PMTiles, memorizzato come semplice JSON all'interno del file.
C'è un limite di dimensione o di numero di tile?
I file caricati sono limitati a 100 MB. I pacchetti di tile molto grandi (decine di migliaia di tile) richiedono più tempo per essere elaborati, perché ogni tile viene letta, calcolata secondo la sua posizione su una curva di Hilbert e riscritta, tutto dentro la scheda del tuo browser.
Cosa succede all'ordine delle tile all'interno del file?
Le tile vengono ordinate in base a un ID sulla curva di Hilbert prima di essere scritte, così le tile vicine tra loro sulla mappa finiscono vicine anche nel file. È proprio questo che permette a un lettore PMTiles di recuperare una piccola area di mappa con pochissime richieste HTTP a intervalli, invece di una richiesta per ogni tile.
Il mio file MBTiles viene caricato da qualche parte?
No. La lettura del database SQLite, il calcolo delle posizioni delle tile, la compressione delle directory e la costruzione dei byte finali del file PMTiles avvengono tutti localmente nel tuo browser, usando una build WebAssembly di SQLite. Il file non lascia mai il tuo dispositivo.
La conversione avviene interamente nel tuo browser usando una build WebAssembly di SQLite. Nessun file viene mai caricato su un server. Tile della mappa © contributori di OpenStreetMap.
Tessere della mappa © contributori di OpenStreetMap, disegnate con Protomaps (ospitato da KONAKTIVE), con CARTO come riserva.
