Por que converter MBTiles para PMTiles
O MBTiles é a forma padrão de empacotar um conjunto inteiro de tiles de mapa em um único arquivo há mais de uma década, e ferramentas como TileMill, Mapbox Studio e QGIS ainda o exportam por padrão. Mas um arquivo MBTiles é um banco de dados SQLite, o que significa que ler até mesmo um único tile exige um mecanismo SQLite, seja a biblioteca embutida de um aplicativo móvel ou um processo completo de servidor de tiles rodando em algum servidor.
O PMTiles elimina essa exigência por completo. É um único arquivo binário simples, no qual cada tile fica em um deslocamento de byte conhecido, endereçado por um pequeno diretório que o cliente pode baixar uma vez e guardar em cache. Um navegador ou uma biblioteca de mapas então busca os tiles individuais usando requisições HTTP range comuns, o que significa que um arquivo PMTiles pode ser servido diretamente por um serviço de arquivos estáticos como S3, Cloudflare R2 ou GitHub Pages, sem servidor de tiles, sem banco de dados e sem nenhum processo de backend.
Esta ferramenta faz a ponte entre os dois formatos sem nenhuma instalação. Basta soltar um arquivo MBTiles e ela lê a tabela de tiles diretamente do banco de dados SQLite embutido, corrige a diferença de coordenadas entre os dois formatos e monta um arquivo PMTiles válido byte a byte, tudo dentro da aba do seu navegador.
Como funciona a conversão
Nenhuma biblioteca JavaScript ou WebAssembly existente consegue escrever um arquivo PMTiles — o pacote oficial "pmtiles" é apenas um leitor, feito para consumir arquivos via HTTP, não para produzi-los. Por isso este conversor implementa o formato binário PMTiles v3 diretamente a partir da especificação publicada: um cabeçalho de 127 bytes contendo os deslocamentos do arquivo, o intervalo de zoom e os limites geográficos; um diretório de localizações de tiles comprimido com gzip; e os próprios bytes brutos dos tiles.
Dois detalhes são os mais importantes para uma conversão correta. Primeiro, o MBTiles armazena as linhas de tiles na ordem "TMS", contando a partir do sul, enquanto o PMTiles conta a partir do norte, como a maioria dos mapas web modernos; o conversor inverte a coordenada Y de cada tile com a fórmula padrão antes de usá-la. Segundo, o PMTiles não endereça os tiles diretamente por z/x/y — cada tile recebe um único ID a partir de uma curva de Hilbert (uma curva que preenche o espaço), escolhida especificamente porque mantém tiles geograficamente próximos também próximos entre si dentro do arquivo resultante, permitindo que um visualizador de mapas carregue uma pequena área usando pouquíssimas requisições HTTP. Cada tile é ordenado por esse ID, gravado no arquivo nessa ordem e indexado em um diretório comprimido que um leitor percorre por busca binária para encontrar qualquer tile.
O resultado deste conversor foi verificado usando a própria biblioteca leitora oficial "pmtiles", o mesmo código que o MapLibre GL usa para abrir arquivos reais, confirmando que cada tile escrito volta idêntico byte a byte na leitura, tanto para conjuntos de tiles pequenos quanto para arquivos grandes o suficiente para exigir a divisão de diretórios do formato em casos com um número muito grande de tiles.
Guia passo a passo
Escolha um arquivo .mbtiles do seu computador, ou clique em "Testar exemplo" para carregar um pequeno conjunto de tiles sintético gerado na hora.
Os tiles de origem são lidos do arquivo MBTiles e desenhados no mapa, para que você confirme que o conjunto de tiles correto foi carregado antes de converter.
Clique em "Converter para PMTiles". A conversão roda inteiramente no seu navegador: lendo cada tile, calculando sua posição na curva de Hilbert e montando o arquivo PMTiles.
Um resumo aparece: quantos tiles foram convertidos, o intervalo de zoom, o formato dos tiles, os limites geográficos e o tamanho final do arquivo PMTiles.
Clique em "Baixar .pmtiles" para salvar o arquivo pronto no seu computador.
Casos de uso reais
Onde migrar de MBTiles para PMTiles realmente vale a pena.
- Publicar tiles em um serviço de arquivos estáticos. O PMTiles pode ser servido diretamente por S3, Cloudflare R2, GitHub Pages ou qualquer serviço simples de arquivos usando requisições HTTP range, sem nenhum processo de servidor de tiles rodando — algo que um arquivo SQLite MBTiles não consegue fazer sozinho.
- Modernizar uma exportação MBTiles antiga. Pacotes de tiles exportados anos atrás do TileMill, Mapbox Studio ou QGIS geralmente ainda estão em MBTiles. Convertê-los para PMTiles os torna utilizáveis nas pilhas de mapas atuais (MapLibre, Protomaps) sem precisar regenerar os tiles a partir dos dados originais.
- Reduzir a infraestrutura de um projeto de mapa pequeno. Um único arquivo PMTiles estático elimina a necessidade de manter um servidor de tiles dedicado só para servir um conjunto de tiles modesto e majoritariamente estático, reduzindo custo de hospedagem e peças móveis para sites menores e ferramentas internas.
- Preparar pacotes de mapas offline para aplicativos de campo. Aplicativos de coleta de dados em campo e de mapeamento offline cada vez mais leem PMTiles diretamente do armazenamento local. Converter mapas-base MBTiles existentes significa um único formato de arquivo tanto para o aplicativo offline quanto para qualquer mapa web que compartilhe as mesmas imagens.
- Arquivar conjuntos de tiles em um formato nativo para nuvem. Como os tiles do PMTiles são endereçados por intervalo de bytes em vez de exigirem consultas a um banco de dados, um arquivo PMTiles arquivado pode ser inspecionado, parcialmente buscado ou servido anos depois sem precisar de nenhum mecanismo de banco de dados específico instalado.
Perguntas frequentes
O que é o PMTiles e em que ele difere do MBTiles?
Os dois empacotam um conjunto inteiro de tiles de mapa em um único arquivo, mas o MBTiles é um banco de dados SQLite, que exige um mecanismo SQLite para ler até mesmo um único tile. O PMTiles é um arquivo binário simples, projetado para que um servidor web (ou até mesmo um serviço de arquivos estáticos como S3 ou GitHub Pages) possa servir tiles individuais usando requisições HTTP range comuns, sem nenhum servidor de tiles ou banco de dados rodando.
Esta ferramenta realmente implementa o formato PMTiles, ou ela chama alguma biblioteca existente?
Ela implementa o formato binário PMTiles v3 diretamente: o cabeçalho de 127 bytes, o diretório de tiles comprimido com gzip e endereçado por um ID de tile da curva de Hilbert, e a seção de dados dos tiles. Pelo que conseguimos apurar ao construir esta ferramenta, nenhuma outra biblioteca JavaScript baseada em navegador consegue escrever um arquivo PMTiles — o pacote oficial "pmtiles" é apenas um leitor — então isso teve que ser construído a partir da especificação publicada.
Como o resultado foi realmente verificado como correto?
Todo arquivo produzido por esta ferramenta foi testado lendo-o de volta com o próprio leitor do pacote oficial "pmtiles" do npm, o mesmo código que o MapLibre e outras ferramentas usam para abrir arquivos PMTiles reais, confirmando que cada tile volta idêntico byte a byte. Isso foi checado tanto para arquivos pequenos quanto para arquivos grandes o suficiente para exigir a divisão em "diretórios-folha" do formato.
Por que as coordenadas Y importam nesta conversão?
O MBTiles armazena as linhas de tiles de cima para baixo na ordem "TMS", contando a partir do sul. O PMTiles (como a maioria dos mapas web modernos) conta a partir do norte. O conversor inverte a coordenada Y de cada tile usando a fórmula padrão, y_new = 2^z − 1 − y_old, antes de calcular sua posição no arquivo de saída, para que os tiles fiquem no lugar certo.
Isso funciona tanto para tiles vetoriais quanto para imagens raster?
Sim. O conversor lê o campo "format" da tabela de metadados do MBTiles para distinguir tiles raster PNG, JPEG e WebP de tiles vetoriais PBF/MVT, e define o tipo de tile correto no cabeçalho do PMTiles para que ferramentas seguintes, como o MapLibre GL, saibam como renderizá-los.
Meus metadados (nome, descrição, atribuição, camadas vetoriais) serão mantidos?
Sim. O nome, a descrição, a atribuição e — no caso de conjuntos de tiles vetoriais — o esquema "vector_layers" da tabela de metadados do MBTiles são copiados para o bloco de metadados do PMTiles, que é armazenado como JSON simples dentro do arquivo.
Existe um limite de tamanho ou de número de tiles?
Os envios são limitados a 100 MB. Pacotes de tiles muito grandes (dezenas de milhares de tiles) demoram mais para processar, já que cada tile é lido, indexado pela sua posição em uma curva de Hilbert e gravado novamente, tudo dentro da aba do seu navegador.
O que acontece com a ordem dos tiles dentro do arquivo?
Os tiles são ordenados por um ID de tile da curva de Hilbert antes de serem gravados, de modo que tiles próximos entre si no mapa acabam próximos entre si também no arquivo. É isso que permite que um leitor de PMTiles busque uma pequena área do mapa com pouquíssimas requisições HTTP range, em vez de uma requisição por tile.
Meu arquivo MBTiles é enviado para algum lugar?
Não. A leitura do banco de dados SQLite, o cálculo das posições dos tiles, a compressão dos diretórios e a montagem dos bytes finais do PMTiles acontecem todos localmente no seu navegador, usando uma versão do SQLite compilada em WebAssembly. O arquivo nunca sai do seu dispositivo.
A conversão roda inteiramente no seu navegador usando uma versão do SQLite compilada em WebAssembly. 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.
