Um visualizador de PMTiles vetoriais que funciona no seu navegador
PMTiles é um formato de arquivo único para mapas em blocos. Um arquivo .pmtiles guarda uma pirâmide inteira de blocos, da vista do mundo no zoom 0 até o nível da rua, além de um índice que diz onde fica cada bloco dentro do arquivo. Como um app de mapa consegue ler qualquer bloco com uma única requisição HTTP por intervalo, basta colocar o arquivo num armazenamento em nuvem comum para usá-lo como mapa, sem nenhum servidor de blocos. Por isso os mapas PMTiles viraram um jeito comum de publicar dados do OpenStreetMap: os mapas base da Protomaps e muitos mapas de cidades e países feitos com o Planetiler são distribuídos como arquivos PMTiles do OpenStreetMap.
Olhar dentro de um é mais difícil. Um .pmtiles é binário, nenhum programa comum o abre, e para ver os blocos vetoriais normalmente é preciso MapLibre, um estilo e um pouco de código. Este visualizador de PMTiles vetoriais online faz esse trabalho por você. Solte um arquivo, ou cole a URL de um arquivo que já está online, e o visualizador lê o cabeçalho e os diretórios, baixa só os blocos na tela, decodifica-os no navegador e desenha cada camada com uma cor própria.
Ele é tanto uma ferramenta de verificação quanto um visualizador. Clique em qualquer feição para ler os atributos, ligue e desligue camadas, veja o tamanho dos blocos em cada nível de zoom e confira o arquivo pelo PMTiles v3 e pela especificação de blocos vetoriais: cabeçalho, compactação, agrupamento, tamanho do diretório raiz, metadados, extensão, contagens de blocos e ETag. Depois exporte as feições visíveis como GeoJSON, salve um PNG ou baixe um relatório técnico. Meu conselho: abra o arquivo pela URL final antes de divulgá-lo. A maioria dos casos de "meu mapa PMTiles não carrega" vem de configurações de CORS ou de intervalos no bucket, e este visualizador mostra isso com um clique.
O que o visualizador de PMTiles vetoriais faz
Aqui está tudo o que a ferramenta faz, na ordem em que você vai encontrar.
- Abrir um arquivo ou uma URL. Arraste um .pmtiles para o mapa, clique em "Abrir PMTiles" ou cole uma URL e aperte Abrir. Não há limite de tamanho: o visualizador lê só o cabeçalho, os diretórios e os blocos de que precisa, de um arquivo do seu disco ou de um servidor. "Testar um exemplo" carrega um pequeno arquivo PMTiles do OpenStreetMap do centro de Paris, e o link de exemplo abre um arquivo de Florença no pmtiles.io.
- Ver o mapa na hora. O visualizador lê a extensão no cabeçalho e vai até os dados. Cada camada é desenhada num canvas com uma cor própria: polígonos como preenchimentos claros, linhas como traços, pontos como pontos com rótulos. Nomes de camada dos esquemas Protomaps, OpenMapTiles e Shortbread, como water, landuse, buildings, roads e places, recebem cores naturais.
- Trabalhar com as camadas. A aba Camadas lista cada camada dos metadados e dos blocos, com os tipos de geometria, o número de feições numa amostra e todos os campos com um valor de exemplo. Ligue e desligue camadas, aperte "Só esta" para ver uma camada sozinha ou clique no quadrado de cor para escolher a sua.
- Clicar para examinar feições. Clique no mapa e um cartão mostra cada feição naquele ponto nas camadas visíveis: camada, tipo de geometria, ID e todos os atributos, por exemplo kind, name e min_zoom de uma rua do OpenStreetMap. A feição fica destacada, e você pode copiá-la como GeoJSON ou baixar o bloco inteiro como arquivo .pbf.
- Ler as informações do arquivo. A aba Arquivo mostra o cabeçalho e os metadados em palavras simples: nome, atribuição, tipo de bloco, compactação dos blocos e dos diretórios, faixa de zoom, extensão, centro, a ferramenta que o criou (por exemplo Planetiler), tamanho do arquivo, número de blocos endereçados e únicos e tamanho dos diretórios.
- Conferir os blocos. O visualizador lê cada entrada dos diretórios e informa, por nível de zoom, o número de blocos e o tamanho total, médio e máximo, além dos dez maiores blocos. Aperte "Ver" para ir até um bloco. A grade de blocos desenha a borda de cada bloco com seu z/x/y e o tamanho guardado.
- Rodar as verificações. A aba Verificações testa o arquivo: versão do cabeçalho, tipo de bloco, compactação, agrupamento, se o diretório raiz cabe nos primeiros 16 KB, metadados e vector_layers, extensão e centro, faixa de zoom e contagens de blocos contra os diretórios, blocos acima de 500 KB, deduplicação, atribuição e, para URLs, o ETag. Cada item é marcado como OK, aviso ou erro, com uma explicação simples.
- Compartilhar um link. Quando você abre um arquivo por uma URL, "Copiar link para este arquivo" gera um link para esta página que abre o mesmo arquivo. Mande para um colega e ele verá o mesmo mapa e as mesmas verificações.
- Aproximar além dos dados. Blocos vetoriais continuam nítidos quando você aproxima além do último nível de zoom, então o visualizador segue desenhando os blocos mais profundos ampliados ("overzoom"). Abaixo do primeiro nível de zoom, um aviso pede que você aproxime.
- Exportar. Baixe as feições visíveis como GeoJSON, a vista do mapa como PNG, o cabeçalho e os metadados como JSON ou um relatório técnico com verificações, cabeçalho, camadas, campos, estatísticas de blocos e recomendações.
Um arquivo local é lido em partes por JavaScript dentro da aba do navegador e nunca é enviado. Uma URL é lida pelo seu navegador direto do servidor dela; este site não vê os dados.
Como ver um arquivo PMTiles, passo a passo
Um exemplo real com a amostra PMTiles do OpenStreetMap do centro de Paris (esquema do mapa base Protomaps, zoom 0 a 12).
A ferramenta abre com um mapa vazio, uma área para soltar arquivos e um campo de URL. Arraste seu .pmtiles para o mapa, clique para escolher um arquivo, cole uma URL ou aperte "Testar um exemplo".
O visualizador lê o cabeçalho e o diretório raiz, vai até a extensão e desenha todas as camadas dos dados do OpenStreetMap: água em azul, parques em verde, edifícios em marrom, ruas em laranja e nomes de lugares em vermelho.
A aba Camadas lista cada camada com sua geometria, as feições encontradas numa amostra e todos os campos. Aqui só roads e water estão ligadas, o que mostra a rede de ruas e o Sena.
Clique numa rua. O cartão mostra a camada, a geometria, o ID e atributos do OpenStreetMap como kind, kind_detail e name, e a rua fica destacada no mapa.
A aba Arquivo traduz o cabeçalho e os metadados em palavras simples: tipo de bloco MVT, compactação gzip, zoom 0 a 12, extensão, centro, número de blocos e tamanho dos diretórios.
A aba Blocos mostra blocos e tamanhos por nível de zoom e os maiores blocos, lidos dos diretórios. Com a grade ligada, a borda de cada bloco é desenhada com seu z/x/y e o tamanho guardado.
A aba Verificações testa o arquivo pelas regras do PMTiles v3 e dos blocos vetoriais. A amostra passa em todas; um arquivo aberto por URL ganha também uma verificação de ETag.
O relatório técnico reúne numa página o resumo, uma prévia do mapa, as verificações, o cabeçalho completo, os metadados, cada camada e campo, as estatísticas de blocos e recomendações. Imprima ou salve como PDF.
Como abrir um arquivo PMTiles: suas opções
Há vários jeitos de abrir um .pmtiles. O certo depende do que você quer: olhar, conferir ou montar um mapa com ele.
- No navegador, com este visualizador. O jeito mais rápido de ver o que há num arquivo vetorial, do seu disco ou de uma URL: sem instalar nada, sem servidor, funciona no Windows, Mac, Linux e em tablets. Ótimo para conferir um arquivo, ler atributos e compartilhar um relatório. Para PMTiles raster (blocos PNG, JPEG, WebP), use o Visualizador de PMTiles deste site.
- Com o visualizador do pmtiles.io. O visualizador oficial da Protomaps mostra o cabeçalho, os metadados e um inspetor de blocos. Serve para uma olhada técnica rápida; este visualizador acrescenta cores por camada, campos de atributos, estatísticas de blocos, verificações e exportações.
- No MapLibre GL JS. Adicione a biblioteca pmtiles, registre o protocolo e aponte uma fonte vetorial para pmtiles://https://example.com/arquivo.pmtiles. Com um estilo (por exemplo os estilos do mapa base Protomaps), você tem um mapa web pronto e rápido. É assim que a maioria dos mapas PMTiles é publicada.
- No QGIS. Uma versão do QGIS que use o GDAL 3.8 ou mais novo abre um .pmtiles pelo driver PMTiles do GDAL: Camada → Adicionar camada → Adicionar camada vetorial, e escolha o arquivo. Cada camada de blocos vira uma camada vetorial. Bom para combinar os dados com outros dados GIS.
- Com a ferramenta de linha de comando pmtiles. O programa go-pmtiles mostra o cabeçalho ("pmtiles show"), recorta uma área ("pmtiles extract"), converte a partir de MBTiles ("pmtiles convert") e serve o arquivo como blocos z/x/y ("pmtiles serve").
- Como MBTiles. Se uma ferramenta só lê MBTiles, converta o arquivo com "pmtiles convert arquivo.pmtiles arquivo.mbtiles". Os blocos continuam iguais; para o caminho inverso, há um conversor de MBTiles para PMTiles grátis neste site.
Uma coisa é igual em todo lugar: um arquivo PMTiles traz dados, não um estilo. Cada app decide como colorir as camadas. Este visualizador escolhe as cores pelo nome das camadas para você ver a estrutura sem escrever um estilo antes.
Como o visualizador lê um arquivo PMTiles e desenha os blocos
Abrir um arquivo PMTiles leva cinco passos: ler o cabeçalho, transformar a posição no mapa num ID de bloco, procurar esse ID nos diretórios, buscar os bytes com uma requisição por intervalo e então descompactar, decodificar e desenhar o bloco. Aqui está exatamente o que acontece, com os números da amostra de Paris.
1. A estrutura do arquivo e o cabeçalho de 127 bytes
Um arquivo PMTiles v3 tem cinco seções numa ordem fixa. Os primeiros 127 bytes são o cabeçalho: a palavra mágica "PMTiles", a versão, a posição e o comprimento de cada outra seção, contagens de blocos, compactação, tipo de bloco, faixa de zoom, extensão e centro. O visualizador lê os primeiros 16.384 bytes numa requisição, que sempre contêm o cabeçalho e o diretório raiz:
bytes 0–126 cabeçalho "PMTiles" + versão 3 + posições, contagens, zoom, extensão
diretório raiz deve terminar antes do byte 16.384
metadados JSON name, attribution, vector_layers, …
diretórios folha opcionais, para arquivos grandes
dados dos blocos os blocos, um depois do outro
amostra Paris raiz 127 + 142 bytes metadados 269 + 870 bytes
blocos 1.139 + 2.929.805 bytes 24 blocos, zoom 0–12
extensão 2.197266, 48.748945, 2.460938, 48.922499As coordenadas são guardadas como inteiros em unidades de 10⁻⁷ grau, então 2,197266° é guardado como 21972660. O visualizador as converte de volta e ajusta o mapa à extensão.
2. De z/x/y para um ID de bloco: a curva de Hilbert
O PMTiles dá a cada bloco do mundo um número, o ID do bloco. Primeiro vêm todos os blocos do zoom 0, depois todos os do zoom 1, e assim por diante. Dentro de um nível de zoom, os blocos seguem uma curva de Hilbert, uma linha que passa por cada bloco e mantém os vizinhos próximos:
primeiro ID do zoom z = (4^z − 1) / 3 0, 1, 5, 21, 85, …
ID do bloco = primeiro ID do zoom z + índice de Hilbert d(x, y)
zoom 1: 1/0/0 → 1 1/0/1 → 2 1/1/1 → 3 1/1/0 → 4
Paris 12/2074/1409
primeiro ID do zoom 12 = (16.777.216 − 1) / 3 = 5.592.405
d(2074, 1409) = 14.248.941
ID do bloco = 19.841.346Como a curva de Hilbert mantém os blocos vizinhos próximos na ordem dos IDs, os blocos de uma cidade ficam juntos no arquivo. Um mapa que se move sobre uma cidade lê então intervalos de bytes vizinhos, algo que caches e CDNs tratam bem.
3. Diretórios: entradas com comprimento de sequência e diretórios folha
Um diretório é uma lista ordenada de entradas. Cada entrada diz: a partir deste ID, tantos blocos seguidos (comprimento de sequência) usam os bytes nesta posição com este comprimento. A lista é guardada coluna por coluna como varints, com os IDs como diferenças, e depois compactada com gzip. Estas são as quatro primeiras entradas da amostra de Paris, os blocos pais do bloco da cidade nos zooms 0 a 3:
entrada ID bloco sequência posição comprimento
0/0/0 0 1 0 65.269
1/1/0 4 1 65.269 76.322
2/2/1 18 1 141.591 124.909
3/4/2 75 1 266.500 116.768
guardado 24 | 0, 4, 14, 57 | 1, 1, 1, 1 | 65269, 76322, … | 1, 0, 0, …
qtde deltas de ID sequências comprimentos posições (0 = logo após o bloco anterior)
sequência 0 → a entrada aponta para um diretório folha, não para um blocoUma sequência maior que 1 é como o PMTiles guarda o mesmo bloco muitas vezes sem custo: dez mil blocos de oceano iguais viram uma só entrada. Quando o diretório raiz não caberia em 16 KB, as entradas são divididas em diretórios folha e a raiz só aponta para eles. Para achar um bloco, o visualizador procura na raiz, segue no máximo três níveis de folhas e guarda em cache cada diretório lido.
4. Ler só o necessário: requisições por intervalo
Com uma URL, cada leitura é uma requisição HTTP por intervalo. Com um arquivo local, é uma fatia do objeto File. Nos dois casos, abrir um arquivo custa uma leitura para o cabeçalho e a raiz, uma para os metadados e depois uma por bloco (mais um diretório folha na primeira visita a uma área):
GET /florence.pmtiles
Range: bytes=0-16383 → 206 Partial Content cabeçalho + raiz
Range: bytes=525-22237 → 206 metadados JSON
Range: bytes=22238-456635 → 206 bloco 0/0/0
o servidor precisa Accept-Ranges: bytes, status 206 para um intervalo
CORS: Access-Control-Allow-Origin para o seu site
um ETag, para perceber um arquivo trocadoSe o servidor ignorar o cabeçalho Range e mandar o arquivo inteiro com status 200, ou se o CORS bloquear a requisição, o visualizador diz isso em palavras simples. Essas duas configurações são o motivo comum de um mapa PMTiles funcionar no notebook e falhar na web.
5. Contar os blocos: a varredura dos diretórios
Para a aba Blocos, o visualizador lê o diretório raiz inteiro e, se somarem 64 MB ou menos (8 MB para uma URL), todos os diretórios folha numa só leitura. Ele expande cada sequência e a divide por nível de zoom usando o primeiro ID de cada zoom:
zoom do ID t = maior z com (4^z − 1) / 3 ≤ t blocos por zoom = Σ sequências dentro desse zoom tamanho por zoom = Σ sequência × comprimento cobertura = blocos / 4^z economia da deduplicação = 1 − tile_contents_count / addressed_tiles_count
Depois os totais são comparados com as três contagens do cabeçalho (blocos endereçados, entradas e conteúdos). Uma diferença indica que o arquivo foi gravado por uma ferramenta com defeito ou que está cortado. Em arquivos do tamanho do planeta, cujos diretórios folha ocupam centenas de MB, a varredura é pulada e o mapa continua funcionando.
6. Descompactar e decodificar o bloco vetorial
O cabeçalho diz como os blocos estão compactados. O gzip é descompactado com o DecompressionStream embutido no navegador. O resultado é uma Mapbox Vector Tile, uma mensagem Protocol Buffers lida pelo mesmo decodificador do Visualizador de MBTiles vetoriais deste site:
varint 300 = 1010 1100 0000 0010 → 0101100 + 0000010 × 128 = 300 zigzag 0 → 0, −1 → 1, 1 → 2, −2 → 3 n = (z >>> 1) ^ −(z & 1) comando = (quantidade << 3) | id MoveTo = 1, LineTo = 2, ClosePath = 7 9 = MoveTo 1 ponto 18 = LineTo 2 pontos 15 = ClosePath anel com área > 0 anel externo, área < 0 buraco
Nomes e valores de atributos são guardados uma vez por camada e cada feição guarda só pares de índices; por isso os blocos do OpenStreetMap com milhares de edifícios ficam em torno de 100 a 200 KB. O decodificador foi comparado com o decodificador de referência da Mapbox em mais de 350.000 feições, sem nenhuma diferença.
7. Desenho, overzoom e detecção de cliques
Cada bloco do mapa é um canvas de 256 × 256 pixels (512 em telas de alta resolução). As unidades do bloco, de 0 a 4096 de lado, são convertidas em pixels. Além do último nível de zoom, o bloco pai é ampliado e deslocado. Um clique é convertido em unidades do bloco e testado contra as feições:
escala = 256 × f / extent f = 2^(z_mapa − z_dados) deslocamento = (x mod f, y mod f) × 256 ponto acerto se distância ≤ 7 px linha acerto se distância a um segmento ≤ 5 px polígono acerto se um raio a partir do clique cruza os anéis um número ímpar de vezes
Como os dados são vetoriais, as linhas são redesenhadas em cada escala e ficam nítidas. Os rótulos seguem o atributo min_zoom que a Protomaps e muitos builds do Planetiler dão a cada feição: um nome só aparece quando o mapa chega a esse zoom, e nomes de lugares ganham dos nomes de POI quando falta espaço. Um teste rápido com o retângulo envolvente descarta a maioria das feições antes do teste exato do clique, então até blocos densos de cidade respondem na hora.
8. Orçamento de tamanho por bloco
Blocos grandes deixam os mapas lentos: cada um precisa ser baixado, descompactado e decodificado antes de aparecer qualquer coisa. O tippecanoe limita os blocos a 500 KB por padrão, e o mesmo limite é comum em serviços de blocos vetoriais. O visualizador pega cada comprimento guardado nos diretórios e marca os níveis de zoom que passam dele:
tamanho guardado = comprimento na entrada do diretório bytes, compactados tamanho médio = tamanho por zoom / blocos por zoom referência maior bloco < 500 KB (512.000 bytes) Florença (pmtiles.io) maior bloco 0/0/0 = 434.398 bytes → OK
Nos arquivos PMTiles do OpenStreetMap, os maiores blocos costumam ser os de zoom baixo, que guardam um país ou um continente inteiro, e os centros urbanos densos nos zooms 12 a 14. A lista dos maiores blocos leva você direto até eles.
PMTiles e os formatos de exportação em detalhe
O que há dentro de um arquivo PMTiles, como ele difere do MBTiles e o que cada download deste visualizador contém.
PMTiles vetorial .pmtiles
Um arquivo PMTiles v3 com tipo de bloco MVT. Cada bloco é uma Mapbox Vector Tile compactada com gzip, com camadas nomeadas. Os metadados JSON costumam ter name, attribution, description e uma lista vector_layers com os campos de cada camada. Arquivos feitos com o Planetiler também registram a hora da geração e dados de replicação do OpenStreetMap.
metadata = {
"name": "Paris, OpenStreetMap sample",
"attribution": "© OpenStreetMap contributors",
"vector_layers": [
{ "id": "roads", "minzoom": 3, "maxzoom": 12,
"fields": { "kind": "String", "kind_detail": "String",
"name": "String", "min_zoom": "Number", … } } ]
}Um arquivo, nenhum servidor, qualquer tamanho, de uma cidade ao planeta inteiro. Precisa de um leitor que aceite requisições por intervalo (MapLibre com a biblioteca pmtiles, OpenLayers, plugins do Leaflet, QGIS ou este visualizador) e de um estilo para parecer um mapa pronto.
PMTiles raster .pmtiles
A mesma estrutura, mas os blocos são imagens: PNG, JPEG, WebP ou AVIF. O estilo fica gravado nos pixels, então o mapa não pode ser reestilizado nem consultado, e fica borrado além do último nível de zoom.
O tipo de bloco no cabeçalho diferencia os dois. Este visualizador manda arquivos raster para o Visualizador de PMTiles deste site, feito para imagens.
PMTiles e MBTiles comparados .pmtiles / .mbtiles
Os dois guardam os mesmos blocos. O MBTiles é um banco SQLite e precisa de um programa ou servidor que rode SQL; o PMTiles é um arquivo simples com índice próprio, do qual um navegador lê blocos avulsos por HTTP. O PMTiles também deduplica blocos iguais com sequências e ordena os blocos numa curva de Hilbert.
Use MBTiles para editar e para ferramentas que esperam esse formato, e PMTiles para publicar na web. Na conversão entre eles, cada bloco fica idêntico byte a byte.
GeoJSON (vista) .geojson
Todas as feições das camadas visíveis nos blocos que cobrem a vista atual, no nível de zoom de dados atual, como uma FeatureCollection RFC 7946 em WGS84. Cada feição mantém os atributos e ganha _layer e _tile. Os polígonos são agrupados com seus buracos.
{ "type": "Feature", "id": 35184380521390,
"properties": { "kind": "highway", "kind_detail": "motorway", "name": "Avenue de Paris",
"min_zoom": 4, "_layer": "roads", "_tile": "11/1037/705" },
"geometry": { "type": "LineString",
"coordinates": [[2.3650217, 48.7375971], [2.3645496, 48.7386726], …] } }As feições são cortadas nas bordas dos blocos, do jeito que estão guardadas. Uma exportação cobre no máximo 64 blocos; aproxime para uma área menor e mais detalhada. Com dados do OpenStreetMap, confira a licença ODbL antes de reutilizar um recorte.
PNG (vista) .png
Uma imagem das camadas vetoriais como aparecem na janela do mapa, com fundo branco, uma barra de título com o nome e o nível de zoom e a atribuição dos metadados.
Útil para documentação ou uma prévia rápida. O mapa base não entra, então não há direitos de imagem de terceiros com que se preocupar.
Cabeçalho e metadados (JSON) .json
O cabeçalho PMTiles completo (posições, comprimentos, contagens, compactação, tipo de bloco, zoom, extensão e centro), os metadados JSON, as estatísticas dos diretórios por nível de zoom e a lista de camadas encontradas nos blocos.
Útil para comparar duas versões de um arquivo ou para copiar a lista vector_layers para um estilo do MapLibre.
Bloco (.pbf) .pbf
O bloco vetorial sob o seu clique, descompactado, exatamente como o MapLibre o recebe. O nome do arquivo traz o z/x/y dele.
Passe-o para outras ferramentas (por exemplo vt2geojson ou um visualizador de protobuf) para depurar um bloco em detalhe.
Relatório técnico .html
Uma página HTML com o resumo do arquivo, uma prévia do mapa, cada verificação, a tabela completa do cabeçalho, os metadados, as camadas com tipos de geometria e campos, os blocos por nível de zoom, os maiores blocos, recomendações e como usar o arquivo.
Ele sai limpo em PDF. Anexe a um chamado ou a uma entrega, para quem recebe ver o que há no arquivo sem abri-lo.
Todas as exportações são feitas no seu navegador a partir do arquivo que você abriu. Nada é enviado a este site.
Quem usa um visualizador de PMTiles vetoriais
O PMTiles levou a hospedagem de mapas dos servidores de blocos para arquivos simples, então hoje muita gente precisa olhar dentro desses arquivos.
- Desenvolvedores de mapas web. Confira um arquivo antes de escrever um estilo do MapLibre: quais camadas existem, como os campos se chamam, em que níveis de zoom os dados aparecem. Abra a URL de produção para ver se requisições por intervalo e CORS funcionam antes de publicar.
- Mapeadores e usuários de dados do OpenStreetMap. Veja um recorte PMTiles do OpenStreetMap da Protomaps ou de um build do Planetiler, clique em ruas, edifícios e lugares e veja exatamente quais tags do OSM chegaram aos blocos.
- Analistas GIS. Confirme que uma saída do tippecanoe, do Planetiler ou do "pmtiles convert" tem as camadas, os atributos e a faixa de zoom certos, e entregue junto com o relatório.
- Times de DevOps e nuvem. Teste um bucket no S3, R2 ou Google Cloud Storage: o visualizador mostra em palavras simples erros de CORS, falta de suporte a intervalos e falta de ETag, e as verificações acham blocos grandes demais e arquivos não agrupados.
- Publicadores de dados. Confira atribuição, extensão, centro e descrição antes de publicar mapas PMTiles, para que os usuários vejam o crédito certo e a vista inicial certa.
- Mapeamento offline e de campo. Confira se um arquivo recortado com "pmtiles extract" cobre a área e os níveis de zoom certos antes de copiá-lo para um aparelho que vai ficar sem sinal.
- Estudantes e professores. Veja como funcionam os mapas nativos da nuvem: ligue a grade de blocos, compare tamanhos entre níveis de zoom, leia o cabeçalho e siga um ID de bloco pelos diretórios.
- Suporte e relatos de bugs. Quando um mapa PMTiles mostra um buraco, ache o bloco, baixe-o como .pbf e anexe ao chamado junto com o relatório.
Perguntas frequentes sobre PMTiles
As 20 perguntas mais feitas sobre arquivos PMTiles e este visualizador.
1. O que é um arquivo PMTiles?
PMTiles é um formato de arquivo único para blocos de mapa, criado pela Protomaps. Ele guarda os blocos de todos os níveis de zoom e um índice compacto (os diretórios), então um leitor consegue buscar qualquer bloco com uma requisição HTTP por intervalo. Você pode hospedá-lo num armazenamento estático comum e usá-lo como mapa sem servidor de blocos.
2. Como abro um arquivo PMTiles?
Para uma olhada rápida, solte-o neste visualizador ou cole a URL dele: nada é instalado nem enviado. Para montar um mapa web, use o MapLibre GL JS com o protocolo pmtiles. O QGIS o abre como camada vetorial quando usa o GDAL 3.8 ou mais novo. A ferramenta de linha de comando pmtiles mostra o cabeçalho e converte para MBTiles. A seção "Como abrir um arquivo PMTiles" acima compara todas as opções.
3. Este visualizador de PMTiles é grátis?
Sim. É grátis, sem conta, sem limite diário e sem marca-d’água nas exportações. Tudo roda no seu navegador, então não há custo de servidor para repassar.
4. Meu arquivo é enviado para algum lugar?
Não. Um arquivo local é lido em partes com a API File do navegador, e os blocos são decodificados e desenhados dentro da sua aba. Quando você abre uma URL, seu navegador busca as partes direto naquele servidor; este site nunca recebe os dados. Só um mapa base, se você ligar um, é carregado do provedor dele.
5. Qual pode ser o tamanho do arquivo?
Não há limite fixo. O visualizador nunca carrega o arquivo inteiro, só o cabeçalho, os diretórios e os blocos na tela, então um arquivo do planeta inteiro com vários GB abre tão rápido quanto um pequeno. Em arquivos muito grandes, as estatísticas de blocos por zoom são puladas, porque só os diretórios já ocupam centenas de MB.
6. Por que minha URL de PMTiles não abre?
Quase sempre é CORS ou requisições por intervalo. O servidor precisa aceitar requisições vindas da sua página (cabeçalho Access-Control-Allow-Origin) e devolver só os bytes pedidos com status 206. Buckets na nuvem precisam de uma regra de CORS para GET e HEAD; algumas CDNs precisam ligar o cache por intervalos de bytes. A mensagem de erro do visualizador diz qual das duas falhou.
7. O que são PMTiles do OpenStreetMap?
Arquivos PMTiles gerados com dados do OpenStreetMap, como o mapa base da Protomaps (camadas earth, water, landuse, landcover, roads, buildings, pois, places, boundaries, transit) ou builds no esquema OpenMapTiles feitos com o Planetiler. Você pode baixar builds diários do planeta ou recortar uma região. Eles estão sob a licença ODbL e exigem o crédito "© OpenStreetMap contributors".
8. Qual a diferença entre PMTiles e MBTiles?
Os dois guardam os mesmos blocos. O MBTiles é um banco SQLite que precisa de um programa ou servidor de blocos para ser lido; o PMTiles é um arquivo simples com índice próprio que um navegador lê por HTTP. O PMTiles também guarda uma só vez os blocos idênticos. Converta entre eles com "pmtiles convert" ou com o conversor de MBTiles para PMTiles deste site, e os blocos continuam iguais.
9. Posso ver PMTiles raster aqui?
Esta página é para blocos vetoriais. Se você abrir um arquivo raster (blocos PNG, JPEG, WebP ou AVIF), o visualizador o reconhece pelo cabeçalho e leva você ao Visualizador de PMTiles deste site, que mostra blocos de imagem.
10. O que significa "agrupado"?
Um arquivo agrupado (clustered) guarda os blocos na ordem do ID, então blocos próximos no mapa também ficam próximos no arquivo. Os leitores podem buscar os vizinhos juntos, e os caches das CDNs funcionam melhor. Os arquivos gravados pelo "pmtiles convert", pelo tippecanoe e pelo Planetiler são agrupados.
11. Por que o diretório raiz precisa caber em 16 KB?
Para que uma requisição dos primeiros 16.384 bytes sempre traga juntos o cabeçalho e o diretório raiz. Assim o leitor sabe onde está cada bloco ou diretório folha depois de uma única ida e volta. Se a raiz for maior, a especificação é quebrada e muitos leitores falham. A aba Verificações confere isso.
12. O que é um ID de bloco?
Um número para cada bloco do mundo. Primeiro vêm todos os blocos do zoom 0, depois os do zoom 1, e assim por diante; dentro de um nível de zoom, os blocos seguem uma curva de Hilbert. O bloco 12/2074/1409 em Paris, por exemplo, tem o ID 19.841.346. Os diretórios associam esses IDs a intervalos de bytes.
13. O que é deduplicação no PMTiles?
Muitos blocos são idênticos, por exemplo mar aberto ou terra vazia em zooms altos. O PMTiles guarda um bloco assim uma vez e faz muitos IDs apontarem para ele, usando sequências para trechos longos. O cabeçalho conta os blocos endereçados e os conteúdos únicos; o visualizador mostra quanto espaço isso economiza.
14. O que significa overzoom?
Um conjunto de blocos tem um último nível de zoom, muitas vezes 14 ou 15 em dados do OpenStreetMap. Se você aproximar mais, o visualizador continua usando esses blocos e os desenha maiores. Como os dados vetoriais são redesenhados, as linhas ficam nítidas. Por isso os mapas base raramente passam do zoom 15.
15. Por que as feições são cortadas nas bordas dos blocos?
Cada bloco vetorial guarda só as partes das feições que caem dentro dele, mais uma pequena margem. Uma rua longa é guardada em vários pedaços, um por bloco, e o renderizador os desenha lado a lado para o corte não aparecer. Na exportação GeoJSON, os pedaços ficam separados, cada um com um atributo _tile.
16. Posso converter PMTiles em GeoJSON?
Para uma área, sim: aproxime até ela e aperte "GeoJSON (vista)". São exportadas as camadas visíveis de até 64 blocos. Para um arquivo inteiro, é melhor exportar dos dados originais, porque os blocos são simplificados e cortados nas bordas.
17. Posso editar um arquivo PMTiles aqui?
Não, o visualizador só lê. Para mudar os dados, edite a fonte e gere o arquivo de novo com o tippecanoe ou o Planetiler. Para mudar só os metadados, use o "pmtiles edit" da ferramenta de linha de comando.
18. Quais ferramentas criam PMTiles vetoriais?
tippecanoe (a partir de GeoJSON, CSV e FlatGeobuf), Planetiler (a partir do OpenStreetMap, inclusive nos esquemas Protomaps e OpenMapTiles), GDAL 3.8 e mais novos, e o "pmtiles convert" a partir de um MBTiles. A aba Arquivo mostra a ferramenta de criação quando os metadados a registram.
19. O que é MLT e por que não aparece?
MLT (MapLibre Tile) é um formato de blocos vetoriais mais novo, com codificação por colunas e compactação melhor. O PMTiles pode guardá-lo com o tipo de bloco 6. Este visualizador decodifica só Mapbox Vector Tiles (MVT) e avisa quando um arquivo contém MLT; o MapLibre GL JS consegue exibir esses arquivos.
20. Funciona no celular ou no tablet?
Sim, em qualquer navegador atual no iOS, Android, Windows, macOS e Linux. Abrir por URL funciona muito bem no celular, porque só os blocos na tela são baixados. Use a versão em tela cheia para ter mais espaço.
Especificações, software e créditos dos dados
O visualizador é feito com especificações abertas, software livre e dados abertos:
- PMTiles (Protomaps) · BSD-3-ClauseEspecificação PMTiles v3 e biblioteca JavaScript pmtiles da Protomaps: estrutura do arquivo, IDs de bloco de Hilbert, diretórios e leitura de cabeçalho, diretórios e blocos a partir de um arquivo ou URL.
- Mapbox Vector Tile Specification · SpecificationEspecificação Mapbox Vector Tile: estrutura protobuf, comandos de geometria e regras de orientação seguidas pelo decodificador.
- Leaflet 1.9 · BSD-2-ClauseMapa interativo e a camada de grade em canvas que desenha os blocos.
- OpenStreetMap · ODbL 1.0Dados de mapa da amostra de Paris e do exemplo de Florença: © OpenStreetMap contributors, sob a Open Database License.
- Protomaps Basemap and pmtiles.io · BSD-3-Clause / ODbLEsquema de mapa base da amostra e o arquivo de exemplo de Florença no pmtiles.io.
- Protomaps (hosted by KONAKTIVE), CARTO, OpenStreetMap, Esri World Imagery · ODbL and provider termsMapas base opcionais: blocos vetoriais próprios hospedados pela KONAKTIVE, com CARTO e OpenStreetMap como reserva, e Esri World Imagery.
A varredura dos diretórios, o decodificador de blocos vetoriais, o renderizador, as verificações e todas as exportações foram escritos para este site e rodam inteiramente no seu navegador.
Ferramentas relacionadas de blocos e arquivos GIS
As verificações seguem as especificações PMTiles v3 e Mapbox Vector Tile 2.1 e a prática comum; passar numa verificação não garante que todo app de mapa aceite o arquivo. Sample data © OpenStreetMap contributors (ODbL), Protomaps. Optional base maps © OpenStreetMap contributors, Protomaps (hosted by KONAKTIVE), CARTO, Esri.
