Cosa fa questo strumento
Un file PMTiles è un unico archivio binario piatto di tile di mappa, costruito in modo che ogni singolo tile possa essere estratto con semplici richieste HTTP a intervalli di byte (byte-range), senza bisogno di una query su database o di un tile server attivo. Questa efficienza ha però un costo per chi vuole guardare dentro il file: non esiste un modo integrato per vedere cosa contiene davvero un file .pmtiles, a meno di collegare una libreria per mappe oppure usare uno strumento a riga di comando.
Questo visualizzatore elimina questo passaggio. Carica un file e lo strumento legge l'header di 127 byte dell'archivio e i metadati JSON per mostrare il formato dei tile, l'intervallo di zoom, i confini geografici e qualsiasi nome, descrizione o attribuzione presente nel file, quindi renderizza ogni tile visibile direttamente su una mappa Leaflet. Tutto avviene in locale: il file viene letto direttamente dal tuo disco tramite la File API del browser e non viene mai inviato a un server.
Come il visualizzatore legge un file PMTiles
Il visualizzatore usa la libreria JavaScript ufficiale "pmtiles", la stessa implementazione di lettura usata da MapLibre GL, insieme a una sorgente basata su File che permette di estrarre intervalli di byte direttamente da un file caricato invece che tramite HTTP. Questa prima lettura recupera solo l'header e la directory compressa dei tile, sufficiente per mostrare subito l'intervallo di zoom, i confini e il formato dell'archivio, ancora prima che un singolo tile sia stato decodificato.
Mentre scorri e ingrandisci la mappa, ogni tile visibile viene richiesto tramite la sua coordinata z/x/y. Il lettore cerca quella coordinata nella directory dell'archivio, organizzata secondo un ID di tile basato su una curva di Hilbert, esegue una ricerca binaria per trovare l'offset in byte e la lunghezza del tile, recupera esattamente quei byte e restituisce l'immagine grezza del tile. Un piccolo layer Leaflet personalizzato racchiude questa ricerca, in modo che i tile appaiano semplicemente sulla mappa come ci si aspetta da qualsiasi altra sorgente di tile, riutilizzando anche il tile disponibile più vicino quando lo zoom supera il livello massimo registrato nell'archivio.
PMTiles: storia e informazioni tecniche
PMTiles nasce da Protomaps, un progetto di mappatura open source basato sull'idea che una mappa non ha bisogno di un server dietro di sé, ma solo di un file ben organizzato e di qualcosa in grado di servire intervalli di byte. Protomaps pubblica la specifica PMTiles stessa come pubblico dominio, mentre le implementazioni di riferimento del lettore e dello scrittore, in Go, JavaScript, Python e diversi altri linguaggi, sono rilasciate sotto licenza BSD 3-Clause. Il formato ha attraversato più di un'iterazione; la versione attuale e l'unica ancora usata attivamente, v3, ha sostituito i layout precedenti con la directory basata su curva di Hilbert, la stessa implementata anche dal convertitore da MBTiles a PMTiles di questo sito.
Il problema che PMTiles risolve è principalmente di costo e complessità. Una piramide completa di tile per l'intero pianeta può contenere centinaia di milioni di singoli tile. La documentazione di Protomaps riporta come esempio 300 milioni di tile che, se archiviati come oggetti separati, potrebbero costare circa 1.500 $ in commissioni di richiesta su storage cloud e richiedere giorni per essere caricati. Un singolo archivio PMTiles racchiude l'intera piramide in un solo file, deduplica internamente i tile identici (Protomaps riporta riduzioni di dimensione del 70% o più per basemap vettoriali globali) e permette a un semplice host di file statici come S3, Cloudflare R2 o GitHub Pages di servire i singoli tile tramite normali richieste HTTP a intervalli di byte, senza bisogno di tile server, database o funzioni serverless, anche se funziona bene anche da AWS Lambda o Cloudflare Workers se se ne vuole comunque uno davanti.
Alcune informazioni tecniche utili da sapere: esistono librerie di lettura ufficiali per JavaScript, Python, Dart, Kotlin/JVM, Go, C++ e Rust, e il formato è supportato direttamente da MapLibre GL JS, Leaflet e OpenLayers. PMTiles è pensato solo per la lettura (read only): non esiste un modo per aggiornare una manciata di tile all'interno di un archivio esistente senza riscrivere l'intero file, un compromesso deliberato in cambio della semplicità del formato e del suo layout a file singolo, adatto a richieste per intervalli di byte. L'header stesso ha una dimensione fissa di 127 byte, abbastanza piccola da poter essere recuperata in un'unica richiesta, permettendo di conoscere immediatamente l'intervallo di zoom, i confini, il formato dei tile e il numero di tile di un archivio, ancora prima di leggerne uno solo.
Guida passo dopo passo
Clicca su "Carica PMTiles" e scegli un file .pmtiles, trascinane uno sul pannello, oppure clicca su "Prova PMTiles di esempio" per caricare un piccolo esempio generato al momento.
I tile dell'archivio vengono letti direttamente dal file e disegnati sulla mappa. Il pannello informazioni file mostra il numero di tile, il formato, l'intervallo di zoom, i confini e qualsiasi metadato, tutto letto direttamente dall'header del file.
Casi d'uso reali
Quando aprire direttamente un file PMTiles, senza scrivere codice, è davvero utile.
- Controllare un file PMTiles prima di pubblicarlo. Dopo aver creato o convertito un archivio PMTiles, aprirlo qui permette di confermare che l'intervallo di zoom, i confini e il formato dei tile siano corretti prima di caricarlo su un host di file statici.
- Ispezionare un dataset aperto scaricato. I progetti che distribuiscono estratti PMTiles, come porzioni regionali di una basemap più grande, possono essere aperti direttamente per vedere cosa contengono prima di scrivere qualsiasi codice che li utilizzi.
- Verificare una conversione da MBTiles a PMTiles. Dopo aver convertito un file con uno strumento come il convertitore da MBTiles a PMTiles di questo sito, ricaricare il risultato in questo visualizzatore conferma che ogni tile sia finito nel posto giusto.
- Rivedere una basemap prima di distribuire un'app di mappe. I team che creano una mappa utilizzabile offline o self-hosted possono visualizzare in anteprima l'esatto archivio PMTiles che la loro app caricherà, individuando un intervallo di zoom sbagliato o un'area vuota prima del rilascio.
- Verificare un tileset archiviato. Poiché PMTiles porta con sé i propri metadati (nome, descrizione, attribuzione, confini), un file archiviato da anni può ancora essere identificato e controllato senza alcuna documentazione esterna.
Domande frequenti
Cos'è un file PMTiles?
PMTiles è un unico file binario piatto che contiene un insieme completo di tile di mappa, indirizzati tramite una piccola directory interna, in modo che ogni singolo tile possa essere letto con normali richieste HTTP a intervalli di byte. È proprio questo che permette a PMTiles di essere servito direttamente da un host di file statici come S3 o GitHub Pages, senza bisogno di un tile server o di un database.
Quali formati di tile può mostrare questo visualizzatore sulla mappa?
Formati di tile raster: PNG, JPEG, WebP e AVIF. L'header del file indica quale formato utilizza, e il visualizzatore lo legge direttamente invece di indovinarlo dall'estensione del file.
Perché un archivio vettoriale (MVT) non mostra un'anteprima sulla mappa?
Gli archivi MVT (Mapbox Vector Tile) memorizzano geometrie e istruzioni di stile, non immagini finite, e per renderizzarli serve un motore di rendering vettoriale come MapLibre GL, che questo sito basato su Leaflet non include. I metadati del file, l'intervallo di zoom, i confini e i nomi dei layer vettoriali vengono comunque mostrati, poiché provengono direttamente dall'header e dai metadati JSON dell'archivio.
Come fa il visualizzatore a leggere effettivamente il file?
Usa la libreria di lettura JavaScript ufficiale "pmtiles" insieme alla File API del browser, così un file caricato viene letto direttamente dal disco in piccoli intervalli di byte, allo stesso modo in cui la libreria legge un archivio remoto tramite HTTP. Il meccanismo non cambia in nulla quando la sorgente è un file locale invece di un URL.
Posso controllare il numero di tile, l'intervallo di zoom e i confini senza aprire uno strumento per mappe?
Sì. Il pannello informazioni file legge questi dati direttamente dall'header di 127 byte del file: zoom minimo e massimo, confini geografici e numero di tile indirizzati, tutto prima che un solo tile venga decodificato.
Cosa succede se ingrandisco oltre il livello di zoom massimo dell'archivio?
Il visualizzatore riutilizza e ritaglia il tile disponibile più vicino e lo ingrandisce, lo stesso comportamento di over-zoom che mostra una normale mappa web ai margini della propria copertura, invece di lasciare uno spazio vuoto.
C'è un limite di dimensione del file?
I caricamenti sono limitati a 100 MB. Poiché PMTiles indirizza i tile tramite intervalli di byte invece di caricare l'intero file in memoria, la navigazione di un archivio grande resta fluida anche vicino a questo limite.
Il mio file PMTiles viene caricato da qualche parte?
No. Il file viene letto interamente nel tuo browser tramite la File API; nessun byte viene mai inviato a un server.
La lettura è basata sulla libreria JavaScript ufficiale pmtiles. Nessun file viene mai caricato su un server. Tile di mappa © contributori di OpenStreetMap.
Tessere della mappa © contributori di OpenStreetMap, disegnate con Protomaps (ospitato da KONAKTIVE), con CARTO come riserva.
