O que esta ferramenta faz
Um arquivo PMTiles é um único arquivo binário plano que reúne tiles de mapa, construído de forma que cada tile possa ser extraído usando simples requisições HTTP por intervalo de bytes, sem precisar de um banco de dados ou de um servidor de tiles em execução. Essa eficiência tem um custo para quem quer olhar dentro do arquivo: não existe uma forma nativa de ver o que um arquivo .pmtiles realmente contém, a menos que você monte uma biblioteca de mapas por conta própria ou rode o arquivo por uma ferramenta de linha de comando.
Este visualizador elimina essa etapa. Basta soltar um arquivo, e ele lê o cabeçalho de 127 bytes do arquivo e os metadados em JSON para mostrar o formato dos tiles, o intervalo de zoom, os limites geográficos e qualquer nome, descrição ou atribuição que o arquivo carregue, depois renderiza cada tile visível diretamente em um mapa Leaflet. Tudo acontece localmente: o arquivo é lido direto do seu disco usando a File API do navegador, e nada é enviado a um servidor.
Como o visualizador lê um arquivo PMTiles
O visualizador usa a biblioteca JavaScript oficial "pmtiles", a mesma implementação de leitura usada pelo MapLibre GL, junto com uma fonte baseada em arquivo que permite extrair intervalos de bytes diretamente de um arquivo enviado, em vez de por HTTP. Essa primeira leitura busca apenas o cabeçalho e o diretório de tiles comprimido, o que já é suficiente para informar o intervalo de zoom, os limites e o formato do arquivo imediatamente, antes mesmo de qualquer tile ser decodificado.
Conforme você move e amplia o mapa, cada tile visível é solicitado pela sua coordenada z/x/y. O leitor procura essa coordenada no diretório do arquivo, que é organizado por um ID de tile baseado em curva de Hilbert, faz uma busca binária para encontrar o deslocamento e o tamanho em bytes do tile, busca exatamente esses bytes e devolve a imagem bruta do tile. Uma pequena camada personalizada do Leaflet envolve essa busca, de modo que os tiles simplesmente aparecem no mapa como em qualquer outra fonte de tiles, inclusive reaproveitando o tile disponível mais próximo quando você amplia além do zoom máximo registrado no arquivo.
PMTiles: história e dados técnicos
O PMTiles vem do Protomaps, um projeto de mapas de código aberto construído sobre a ideia de que um mapa não precisa de um servidor por trás, apenas de um arquivo bem organizado e de algo capaz de servir intervalos de bytes. O Protomaps publica a própria especificação do PMTiles em domínio público, enquanto as implementações de referência do leitor e do gravador, em Go, JavaScript, Python e várias outras linguagens, são lançadas sob a licença BSD 3-Clause. O formato já passou por mais de uma versão; a versão atual e a única usada ativamente, v3, substituiu layouts anteriores pelo diretório em curva de Hilbert que o próprio conversor de MBTiles para PMTiles deste site também usa.
O problema que o PMTiles resolve é, em grande parte, de custo e complexidade. Uma pirâmide de tiles completa do mundo todo pode ter centenas de milhões de tiles individuais. A própria documentação do Protomaps dá um exemplo de 300 million tiles que, armazenados como objetos separados, poderiam custar cerca de $1,500 em taxas de requisição de armazenamento na nuvem e levar dias para o envio. Um único arquivo PMTiles empacota toda essa pirâmide em um só arquivo, elimina tiles idênticos duplicados internamente (o Protomaps relata reduções de tamanho de 70% ou mais em basemaps vetoriais globais) e permite que um host de arquivos estático simples, como S3, Cloudflare R2 ou GitHub Pages, sirva tiles individuais por meio de requisições HTTP por intervalo comuns, sem precisar de servidor de tiles, banco de dados ou função serverless, embora também funcione bem a partir de AWS Lambda ou Cloudflare Workers, caso você queira colocar um desses na frente.
Alguns dados técnicos que vale a pena conhecer: existem bibliotecas leitoras oficiais para JavaScript, Python, Dart, Kotlin/JVM, Go, C++ e Rust, e o formato é suportado diretamente por MapLibre GL JS, Leaflet e OpenLayers. O PMTiles é, por design, somente leitura: não há como atualizar apenas alguns tiles dentro de um arquivo existente sem reescrever o arquivo inteiro, uma escolha deliberada em troca da simplicidade do formato e do seu layout de arquivo único, adequado a requisições por intervalo de bytes. O próprio cabeçalho tem um tamanho fixo de 127 bytes, pequeno o suficiente para que um leitor o busque em uma única requisição e saiba imediatamente o intervalo de zoom, os limites, o formato dos tiles e a quantidade de tiles do arquivo, antes mesmo de ler um único tile.
Guia passo a passo
Clique em "Upload PMTiles" e escolha um arquivo .pmtiles, arraste e solte um arquivo no painel, ou clique em "Try Sample PMTiles" para carregar um pequeno exemplo gerado na hora.
Os tiles do arquivo são lidos diretamente do arquivo e desenhados no mapa. O painel de informações do arquivo mostra a quantidade de tiles, o formato, o intervalo de zoom, os limites e quaisquer metadados retirados diretamente do cabeçalho do próprio arquivo.
Casos de uso reais
Situações em que abrir um arquivo PMTiles diretamente, sem escrever nenhum código, realmente ajuda.
- Conferir um arquivo PMTiles antes de publicá-lo. Depois de criar ou converter um arquivo PMTiles, abri-lo aqui confirma que o intervalo de zoom, os limites e o formato dos tiles estão corretos antes de enviá-lo a um host de arquivos estático.
- Inspecionar um conjunto de dados aberto baixado. Projetos que distribuem recortes em PMTiles, como cortes regionais de um basemap maior, podem ser abertos diretamente para ver o que contêm antes de escrever qualquer código contra eles.
- Verificar uma conversão de MBTiles para PMTiles. Depois de converter um arquivo com uma ferramenta como o conversor de MBTiles para PMTiles deste site, carregar o resultado de volta neste visualizador confirma que todos os tiles foram parar no lugar certo.
- Revisar um basemap antes de publicar um aplicativo de mapa. Equipes que constroem um mapa autônomo ou hospedado internamente podem pré-visualizar exatamente o arquivo PMTiles que o aplicativo vai carregar, identificando um intervalo de zoom errado ou uma área vazia antes do lançamento.
- Auditar um conjunto de tiles arquivado. Como o PMTiles carrega seus próprios metadados (nome, descrição, atribuição, limites), um arquivo arquivado há anos ainda pode ser identificado e conferido sem nenhuma documentação externa.
Perguntas frequentes
O que é um arquivo PMTiles?
PMTiles é um único arquivo binário plano que guarda um conjunto completo de tiles de mapa, endereçados por um pequeno diretório interno, de forma que cada tile possa ser lido usando requisições HTTP por intervalo comuns. É isso que permite servir o PMTiles diretamente de um host de arquivos estático, como S3 ou GitHub Pages, sem precisar de servidor de tiles nem de banco de dados.
Quais formatos de tile este visualizador consegue mostrar no mapa?
Formatos de tile raster: PNG, JPEG, WebP e AVIF. O próprio cabeçalho do arquivo informa qual deles está em uso, e o visualizador lê essa informação diretamente, em vez de tentar adivinhar pela extensão do arquivo.
Por que um arquivo vetorial (MVT) não mostra uma prévia no mapa?
Arquivos MVT (Mapbox Vector Tile) armazenam geometria e instruções de estilo, não imagens prontas, e renderizá-los exige um renderizador de mapas vetoriais como o MapLibre GL, que este site, baseado em Leaflet, não inclui. Os metadados do arquivo, o intervalo de zoom, os limites e os nomes das camadas vetoriais continuam sendo exibidos, já que vêm diretamente do cabeçalho e dos metadados em JSON do arquivo.
Como o visualizador realmente lê o arquivo?
Ele usa a biblioteca leitora oficial "pmtiles" em JavaScript junto com a File API do navegador, de modo que um arquivo enviado é lido diretamente do disco em pequenos intervalos de bytes, da mesma forma que a biblioteca lê um arquivo remoto por HTTP. Nada no mecanismo muda quando a origem é um arquivo local em vez de uma URL.
Posso conferir a quantidade de tiles, o intervalo de zoom e os limites sem abrir uma ferramenta de mapa?
Sim. O painel de informações do arquivo lê tudo isso diretamente do cabeçalho de 127 bytes do arquivo: zoom mínimo e máximo, limites geográficos e o número de tiles endereçados, tudo antes de um único tile ser decodificado.
O que acontece se eu ampliar além do nível de zoom máximo do arquivo?
O visualizador reaproveita e recorta o tile disponível mais próximo e o amplia, o mesmo comportamento de zoom excedente que um mapa web comum mostra na borda de suas imagens, em vez de deixar um espaço em branco.
Existe um limite de tamanho de arquivo?
O envio é limitado a 100 MB. Como o PMTiles endereça os tiles por intervalo de bytes em vez de carregar o arquivo inteiro na memória, navegar por um arquivo grande continua rápido mesmo perto desse limite.
Meu arquivo PMTiles é enviado a algum lugar?
Não. O arquivo é lido inteiramente no seu navegador usando a File API; nenhum byte é enviado a um servidor.
A leitura é feita pela biblioteca JavaScript oficial pmtiles. Nenhum arquivo é enviado a um servidor. Tiles de mapa © colaboradores do OpenStreetMap.
Blocos do mapa © colaboradores do OpenStreetMap, desenhados com Protomaps (hospedado por KONAKTIVE), com CARTO como reserva.
