Qué hace esta herramienta
Un archivo PMTiles es un único archivo binario plano que contiene mosaicos de mapa, construido de forma que se puedan extraer mosaicos individuales usando simples solicitudes HTTP de rango de bytes, en lugar de una consulta a una base de datos o un servidor de mosaicos en ejecución. Esa eficiencia tiene un costo para quien intenta mirar dentro de uno: no existe una forma incorporada de ver qué contiene realmente un archivo .pmtiles sin conectar tú mismo una librería de mapas o pasarlo por una herramienta de línea de comandos.
Este visor elimina ese paso. Suelta un archivo y la herramienta lee el encabezado de 127 bytes del archivo y sus metadatos JSON para mostrar el formato de mosaico, el rango de zoom, los límites geográficos y cualquier nombre, descripción o atribución que lleve el archivo, y luego renderiza cada mosaico visible directamente en un mapa Leaflet. Todo ocurre de forma local: el archivo se lee directamente desde tu disco usando la File API del navegador, y nunca se envía nada a un servidor.
Cómo lee el visor un archivo PMTiles
El visor usa la librería oficial de JavaScript "pmtiles", la misma implementación de lectura que usa MapLibre GL, junto con una fuente basada en archivo que le permite extraer rangos de bytes directamente de un archivo subido en lugar de por HTTP. Esa primera lectura obtiene solo el encabezado y el directorio de mosaicos comprimido, lo cual basta para informar de inmediato el rango de zoom, los límites y el formato del archivo, antes de que se haya decodificado un solo mosaico.
A medida que desplazas el mapa y haces zoom, cada mosaico visible se solicita por su coordenada z/x/y. El lector busca esa coordenada en el directorio del archivo, organizado mediante un ID de mosaico basado en una curva de Hilbert, realiza una búsqueda binaria para encontrar el desplazamiento en bytes y la longitud del mosaico, obtiene exactamente esos bytes y devuelve la imagen de mosaico sin procesar. Una pequeña capa personalizada de Leaflet envuelve esa búsqueda para que los mosaicos simplemente aparezcan en el mapa como cabría esperar de cualquier otra fuente de mosaicos, incluida la reutilización del mosaico disponible más cercano cuando haces zoom más allá del nivel de zoom máximo registrado en el archivo.
PMTiles: historia y datos técnicos
PMTiles proviene de Protomaps, un proyecto de mapas de código abierto construido sobre la idea de que un mapa no necesita un servidor detrás, solo un archivo bien organizado y algo capaz de servir rangos de bytes. Protomaps publica la especificación de PMTiles como dominio público, mientras que las implementaciones de referencia del lector y del escritor, en Go, JavaScript, Python y varios otros lenguajes, se publican bajo la licencia BSD 3-Clause. El formato ha pasado por más de una iteración; la versión actual, y la única que se usa activamente, v3, reemplazó los diseños anteriores con el directorio basado en curva de Hilbert que también implementa el conversor de MBTiles a PMTiles de este mismo sitio.
El problema que resuelve PMTiles es sobre todo de costo y complejidad. Una pirámide de mosaicos completa a escala mundial puede contener cientos de millones de mosaicos individuales. La propia documentación de Protomaps da un ejemplo de 300 million tiles almacenados como objetos independientes, que podrían costar alrededor de $1,500 en tarifas de solicitudes de almacenamiento en la nube y tardar días en subirse. Un único archivo PMTiles empaqueta toda esa pirámide en un solo archivo, deduplica internamente los mosaicos idénticos (Protomaps reporta reducciones de tamaño del 70% o más en mapas base vectoriales globales), y permite que un servidor de archivos estáticos sencillo, como S3, Cloudflare R2 o GitHub Pages, sirva mosaicos individuales mediante solicitudes HTTP de rango comunes, sin necesidad de un servidor de mosaicos, una base de datos ni una función serverless, aunque también funciona bien desde AWS Lambda o Cloudflare Workers si de verdad quieres tener uno delante.
Algunos datos técnicos que vale la pena conocer: existen librerías de lectura oficiales para JavaScript, Python, Dart, Kotlin/JVM, Go, C++ y Rust, y el formato es compatible directamente con MapLibre GL JS, Leaflet y OpenLayers. PMTiles es de solo lectura por diseño; no hay forma de actualizar un puñado de mosaicos dentro de un archivo existente sin reescribir el archivo completo, una compensación deliberada a cambio de la simplicidad del formato y de su diseño de un solo archivo, apto para solicitudes de rango de bytes. El propio encabezado tiene un tamaño fijo de 127 bytes, lo bastante pequeño como para que un lector lo obtenga en una sola solicitud y conozca de inmediato el rango de zoom, los límites, el formato de mosaico y el número de mosaicos de un archivo, antes de leer un solo mosaico.
Guía paso a paso
Haz clic en "Upload PMTiles" y elige un archivo .pmtiles, arrastra y suelta uno sobre el panel, o haz clic en "Try Sample PMTiles" para cargar un pequeño ejemplo generado al instante.
Los mosaicos del archivo se leen directamente desde el archivo y se dibujan en el mapa. El panel de información del archivo muestra el número de mosaicos, el formato, el rango de zoom, los límites y cualquier metadato, directamente desde el propio encabezado del archivo.
Casos de uso reales
Dónde ayuda de verdad abrir un archivo PMTiles directamente, sin escribir código.
- Verificar un archivo PMTiles antes de publicarlo. Después de crear o convertir un archivo PMTiles, abrirlo aquí confirma que el rango de zoom, los límites y el formato de mosaico son correctos antes de subirlo a un servidor de archivos estáticos.
- Inspeccionar un conjunto de datos abierto descargado. Los proyectos que distribuyen extractos PMTiles, como recortes regionales de un mapa base más grande, se pueden abrir directamente para ver qué contienen antes de escribir código alguno que los use.
- Verificar una conversión de MBTiles a PMTiles. Después de convertir un archivo con una herramienta como el conversor de MBTiles a PMTiles de este sitio, cargar el resultado de nuevo en este visor confirma que cada mosaico terminó en el lugar correcto.
- Revisar un mapa base antes de implementar una aplicación de mapas. Los equipos que crean un mapa que funciona sin conexión o autoalojado pueden previsualizar el archivo PMTiles exacto que su aplicación cargará, detectando un rango de zoom incorrecto o un área vacía antes de publicarlo.
- Auditar un conjunto de mosaicos archivado. Como PMTiles lleva sus propios metadatos (nombre, descripción, atribución, límites), un archivo guardado desde hace años se puede identificar y comprobar sin ninguna documentación externa.
Preguntas frecuentes
¿Qué es un archivo PMTiles?
PMTiles es un único archivo binario plano que contiene un conjunto completo de mosaicos de mapa, direccionados mediante un pequeño directorio interno para que los mosaicos individuales se puedan leer usando solicitudes HTTP de rango comunes. Eso es lo que permite servir PMTiles directamente desde un servidor de archivos estáticos como S3 o GitHub Pages, sin necesidad de un servidor de mosaicos ni de una base de datos.
¿Qué formatos de mosaico puede mostrar este visor en el mapa?
Formatos de mosaico ráster: PNG, JPEG, WebP y AVIF. El propio encabezado del archivo indica cuál usa, y el visor lee ese dato directamente en lugar de adivinarlo a partir de la extensión del archivo.
¿Por qué un archivo vectorial (MVT) no muestra una vista previa del mapa?
Los archivos MVT (Mapbox Vector Tile) almacenan geometría e instrucciones de estilo, no imágenes terminadas, y renderizarlos requiere un renderizador de mapas vectoriales como MapLibre GL, que este sitio basado en Leaflet no incluye. Los metadatos del archivo, el rango de zoom, los límites y los nombres de las capas vectoriales sí se muestran, ya que provienen directamente del encabezado del archivo y de sus metadatos JSON.
¿Cómo lee realmente el archivo el visor?
Usa la librería oficial de lectura de JavaScript "pmtiles" junto con la File API del navegador, de modo que un archivo subido se lee directamente desde el disco en pequeños rangos de bytes, de la misma forma en que la librería lee un archivo remoto por HTTP. El mecanismo no cambia en nada cuando el origen es un archivo local en lugar de una URL.
¿Puedo ver el número de mosaicos, el rango de zoom y los límites sin abrir una herramienta de mapas?
Sí. El panel de información del archivo lee estos datos directamente del encabezado de 127 bytes del archivo: zoom mínimo y máximo, límites geográficos y el número de mosaicos direccionados, todo antes de decodificar un solo mosaico.
¿Qué ocurre si hago zoom más allá del nivel de zoom máximo del archivo?
El visor reutiliza y recorta el mosaico disponible más cercano y lo amplía, el mismo comportamiento de sobre-zoom que muestra un mapa web normal en el límite de sus imágenes, en lugar de dejar un espacio en blanco.
¿Existe un límite de tamaño de archivo?
Las subidas están limitadas a 100 MB. Como PMTiles direcciona los mosaicos por rango de bytes en lugar de cargar el archivo completo en memoria, navegar por un archivo grande se mantiene fluido incluso cerca de ese límite.
¿Se sube mi archivo PMTiles a algún servidor?
No. El archivo se lee por completo en tu navegador usando la File API; nunca se envía ningún byte a un servidor.
La lectura funciona gracias a la librería oficial de JavaScript pmtiles. Ningún archivo se sube nunca a un servidor. Mosaicos de mapa © colaboradores de OpenStreetMap.
Teselas del mapa © colaboradores de OpenStreetMap, dibujadas con Protomaps (alojado por KONAKTIVE), con CARTO como respaldo.
