Por qué convertir de MBTiles a PMTiles
MBTiles ha sido la forma estándar de empaquetar un conjunto completo de teselas de mapa en un solo archivo durante más de una década, y herramientas como TileMill, Mapbox Studio y QGIS todavía lo exportan por defecto. Pero un archivo MBTiles es una base de datos SQLite, lo que significa que leer aunque sea una sola tesela requiere un motor SQLite, ya sea la biblioteca integrada de una app móvil o un proceso completo de servidor de teselas ejecutándose en algún servidor.
PMTiles elimina por completo ese requisito. Es un único archivo binario plano donde cada tesela vive en un desplazamiento de bytes conocido, direccionado mediante un pequeño directorio que un cliente puede descargar una vez y guardar en caché. Un navegador o una biblioteca de mapas obtiene entonces cada tesela mediante peticiones HTTP de rango normales, lo que significa que un archivo PMTiles se puede servir directamente desde un alojamiento de archivos estático como S3, Cloudflare R2 o GitHub Pages, sin servidor de teselas, sin base de datos y sin ningún proceso de backend.
Esta herramienta une ambos formatos sin necesidad de instalar nada. Arrastra un archivo MBTiles y la herramienta lee la tabla de teselas directamente desde la base de datos SQLite integrada, corrige la diferencia de coordenadas entre ambos formatos y ensambla un archivo PMTiles válido byte a byte, todo dentro de la pestaña de tu navegador.
Cómo funciona la conversión
Ninguna biblioteca de JavaScript o WebAssembly existente puede escribir un archivo PMTiles: el paquete oficial "pmtiles" es solo un lector, pensado para consumir archivos por HTTP, no para producirlos. Por eso este convertidor implementa el formato binario PMTiles v3 directamente a partir de su especificación publicada: una cabecera de 127 bytes que guarda los desplazamientos del archivo, el rango de zoom y los límites geográficos; un directorio comprimido con gzip de las ubicaciones de las teselas; y los bytes en bruto de las propias teselas.
Dos detalles son los más importantes para lograr una conversión correcta. Primero, MBTiles guarda las filas de teselas en orden "TMS", contando desde el sur, mientras que PMTiles cuenta desde el norte como la mayoría de los mapas web modernos; el convertidor invierte la coordenada Y de cada tesela con la fórmula estándar antes de usarla. Segundo, PMTiles no direcciona las teselas por z/x/y directamente: cada tesela recibe un único identificador a partir de una curva de Hilbert que recorre el espacio, elegida precisamente porque mantiene juntas en el archivo resultante a las teselas que están cerca geográficamente, de modo que un visor de mapas puede cargar un área pequeña usando muy pocas peticiones HTTP. Cada tesela se ordena según este identificador, se escribe en el archivo en ese orden y se indexa en un directorio comprimido que un lector recorre mediante búsqueda binaria para encontrar cualquier tesela dada.
El resultado de este convertidor se verificó usando la propia biblioteca lectora oficial "pmtiles", el mismo código que usa MapLibre GL para abrir archivos reales, confirmando que cada tesela que escribe vuelve a leerse idéntica byte a byte, tanto para conjuntos de teselas pequeños como para archivos lo bastante grandes como para requerir la división en directorios del formato, pensada para cantidades muy grandes de teselas.
Guía paso a paso
Elige un archivo .mbtiles de tu computadora, o haz clic en "Probar ejemplo" para cargar un conjunto de teselas sintético y pequeño, generado en el momento.
Las teselas de origen se leen del archivo MBTiles y se dibujan en el mapa, para que puedas confirmar que se cargó el conjunto de teselas correcto antes de convertir.
Haz clic en "Convertir a PMTiles". La conversión se ejecuta por completo en tu navegador: lee cada tesela, calcula su posición en la curva de Hilbert y ensambla el archivo PMTiles.
Aparece un resumen: cuántas teselas se convirtieron, el rango de zoom, el formato de las teselas, los límites geográficos y el tamaño final del archivo PMTiles.
Haz clic en "Descargar .pmtiles" para guardar el archivo terminado en tu computadora.
Casos de uso reales
Dónde realmente vale la pena pasar de MBTiles a PMTiles.
- Publicar teselas en un alojamiento de archivos estático. PMTiles se puede servir directamente desde S3, Cloudflare R2, GitHub Pages o cualquier alojamiento de archivos simple usando peticiones HTTP de rango, sin ningún proceso de servidor de teselas ejecutándose, algo que un archivo SQLite de MBTiles no puede hacer por sí solo.
- Modernizar una exportación antigua de MBTiles. Los paquetes de teselas exportados hace años desde TileMill, Mapbox Studio o QGIS suelen seguir siendo MBTiles. Convertirlos a PMTiles los hace utilizables en las pilas de mapas actuales (MapLibre, Protomaps) sin necesidad de volver a generar las teselas desde los datos de origen.
- Reducir la infraestructura de un proyecto de mapas pequeño. Un único archivo PMTiles estático elimina la necesidad de ejecutar y mantener un servidor de teselas dedicado solo para servir un conjunto de teselas modesto y casi siempre estático, reduciendo el costo de alojamiento y las piezas móviles en sitios pequeños y herramientas internas.
- Preparar paquetes de mapas sin conexión para apps de campo. Las apps de recolección de datos de campo y de mapeo sin conexión leen cada vez más PMTiles directamente desde el almacenamiento local. Convertir los mapas base MBTiles existentes permite usar un solo formato de archivo tanto en la app sin conexión como en cualquier mapa web que comparta la misma imagen.
- Archivar conjuntos de teselas en un formato nativo de la nube. Como las teselas de PMTiles se direccionan por rango de bytes en lugar de requerir consultas a una base de datos, un archivo PMTiles archivado se puede inspeccionar, obtener parcialmente o servir años después sin necesitar instalado ningún motor de base de datos en particular.
Preguntas frecuentes
¿Qué es PMTiles y en qué se diferencia de MBTiles?
Ambos empaquetan un conjunto completo de teselas de mapa en un solo archivo, pero MBTiles es una base de datos SQLite, que necesita un motor SQLite para leer aunque sea una sola tesela. PMTiles es un archivo binario simple diseñado para que un servidor web (o incluso un alojamiento de archivos estático como S3 o GitHub Pages) pueda servir teselas individuales mediante peticiones HTTP de rango normales, sin ningún servidor de teselas ni base de datos en ejecución.
¿Esta herramienta implementa realmente el formato PMTiles, o llama a alguna biblioteca existente?
Implementa directamente el formato binario PMTiles v3: la cabecera de 127 bytes, el directorio de teselas comprimido con gzip y direccionado mediante un identificador de tesela basado en una curva de Hilbert, y la sección de datos de las teselas. Hasta donde pudimos determinar al construir esta herramienta, ninguna otra biblioteca de JavaScript que funcione en el navegador puede escribir un archivo PMTiles (el paquete oficial "pmtiles" es solo un lector), así que hubo que construirla a partir de la especificación publicada.
¿Cómo se verificó realmente que el resultado fuera correcto?
Cada archivo que produce esta herramienta se probó leyéndolo de nuevo con el propio lector del paquete oficial de npm "pmtiles", el mismo código que usan MapLibre y otras herramientas para abrir archivos PMTiles reales, y confirmando que cada tesela vuelve a leerse idéntica byte a byte. Esto se comprobó tanto en archivos pequeños como en archivos lo bastante grandes como para requerir la división en "directorios hoja" del formato.
¿Por qué importan las coordenadas Y en esta conversión?
MBTiles guarda las filas de teselas de arriba abajo en orden "TMS", contando desde el sur. PMTiles (como la mayoría de los mapas web modernos) cuenta desde el norte. El convertidor invierte la coordenada Y de cada tesela usando la fórmula estándar, y_new = 2^z − 1 − y_old, antes de calcular su posición en el archivo de salida, de modo que las teselas terminen en el lugar correcto.
¿Funciona tanto con teselas vectoriales como con imágenes ráster?
Sí. El convertidor lee el campo "format" de la tabla de metadatos de MBTiles para distinguir las teselas ráster PNG, JPEG y WebP de las teselas vectoriales PBF/MVT, y establece el tipo de tesela correcto en la cabecera de PMTiles para que herramientas posteriores como MapLibre GL sepan cómo dibujarlas.
¿Se conservarán mis metadatos (nombre, descripción, atribución, capas vectoriales)?
Sí. El nombre, la descripción, la atribución y, en el caso de conjuntos de teselas vectoriales, el esquema "vector_layers" de la tabla de metadatos de MBTiles se copian al bloque de metadatos de PMTiles, que se guarda como JSON simple dentro del archivo.
¿Hay un límite de tamaño o de número de teselas?
Las subidas están limitadas a 100 MB. Los paquetes de teselas muy grandes (decenas de miles de teselas) tardan más en procesarse, ya que cada tesela se lee, se ubica según su posición en una curva de Hilbert y se vuelve a escribir, todo dentro de la pestaña de tu navegador.
¿Qué pasa con el orden de las teselas dentro del archivo?
Las teselas se ordenan según un identificador de curva de Hilbert antes de escribirse, de modo que las teselas que están cerca en el mapa también terminan cerca dentro del archivo. Esto es lo que permite que un lector de PMTiles obtenga un área pequeña del mapa con muy pocas peticiones HTTP de rango, en lugar de una petición por cada tesela.
¿Se sube mi archivo MBTiles a algún servidor?
No. Leer la base de datos SQLite, calcular la posición de las teselas, comprimir los directorios y ensamblar los bytes finales de PMTiles ocurre todo localmente en tu navegador, usando una compilación de SQLite en WebAssembly. El archivo nunca sale de tu dispositivo.
La conversión se ejecuta por completo en tu navegador usando una compilación de SQLite en WebAssembly. Nunca se sube ningún archivo a un servidor. Teselas de mapa © colaboradores de OpenStreetMap.
Teselas del mapa © colaboradores de OpenStreetMap, dibujadas con Protomaps (alojado por KONAKTIVE), con CARTO como respaldo.
