Blog SIG & Territorios

Introducción: ¿Qué es el formato MBTiles?

El formato MBTiles es un formato de archivo para almacenar mosaicos de mapas (ráster o vectoriales) en una base de datos SQLite, un motor de base de datos ligero e independiente.

Diseñado inicialmente por Mapbox, este formato ha sido ampliamente adoptado en las comunidades de SIG, cartografía y mapas web por su portabilidad, facilidad de uso y compatibilidad con numerosas herramientas.

En la práctica, un archivo .mbtiles es una única base de datos que puede contener miles o incluso millones de mosaicos geográficos organizados por niveles de zoom, columnas y filas. Esto evita la necesidad de una compleja estructura de árbol de archivos en el disco, al tiempo que facilita la distribución (en la web, vía USB o en modo desconectado).

El formato MBTiles puede contener :

• Mosaicos rasterizados (normalmente PNG o JPEG),
• O mosaicos vectoriales (en formato MVT – Mapbox Vector Tiles -),
• Y metadatos (descripción, atribución, formato, etc.).

Gracias a su formato SQLite, MBTiles puede leerse fácilmente con herramientas como sqlite3, DB Browser for SQLite, u operarse a través de servidores ligeros (como Flask o TileServer-PHP), lo que lo hace muy adecuado para formación, demostraciones o uso offline.

Estructura interna de un archivo MBTiles

Un archivo MBTiles es una base de datos SQLite estructurada según un esquema sencillo y normalizado, que permite almacenar eficazmente mosaicos de mapas en forma raster (PNG, JPEG) o vectorial (PBF).

1. Las tablas principales

Según la especificación oficial (https://github.com/mapbox/mbtiles-spec), un archivo .mbtiles contiene al menos

a) tiles

Es la tabla central. Contiene las baldosas codificadas, cada una identificada por sus coordenadas zoom, columna (x) y línea (y):

CREATE TABLE tiles (
zoom_level INTEGER,
tile_column INTEGER,
tile_row INTEGER,
tile_data BLOB
);

Nota: MBTiles utiliza el sistema de coordenadas TMS (Tile Map Service), lo que significa que el eje vertical (Y) está invertido respecto al esquema XYZ utilizado por Leaflet. Algunos servidores o visualizadores lo corrigen automáticamente.

b) metadatos

Esta tabla contiene información general sobre el fichero y los tiles que contiene, por ejemplo :

CREATE TABLE metadata (
  name TEXT,
  value TEXT
);

Algunos campos comunes :

• name: nombre del tileset ;
• format: formato del tileset (png, jpg, pbf);
• minzoom, maxzoom: niveles de zoom disponibles;
• bounds: extensión geográfica (minlon,minlat,maxlon,maxlat) ;
• centro: coordenadas del centro del mapa (lon,lat,zoom) ;
• type: tipo de mapa (baselayer, overlay);
• descripción: texto explicativo.

2.Indexación

Los archivos MBTiles pueden incluir índices para acelerar el acceso a los mosaicos, pero no es obligatorio.

3.Otras vistas y variantes

Algunas herramientas (como MapTiler o TileMill) generan vistas adicionales o esquemas alternativos, como la vista de mapa asociada a una tabla de imágenes en un formato optimizado (deduplicación de tiles).

Por ejemplo:

CREATE TABLE images (
  tile_id TEXT,
  tile_data BLOB
);

CREATE TABLE map (
  zoom_level INTEGER,
  tile_column INTEGER,
  tile_row INTEGER,
  tile_id TEXT
);

Esto permite almacenar cada imagen una sola vez, aunque se utilice en varias coordenadas.

He aquí una clara comparación entre los dos tipos de contenido que puede almacenar el formato MBTiles:

Raster vs Vector: Dos tipos de mosaico en los archivos MBTiles

El formato MBTiles es versátil: puede contener mosaicos rasterizados (imágenes) o mosaicos vectoriales (datos geográficos codificados). Cada enfoque tiene sus ventajas y es adecuado para diferentes usos.

MBTiles Raster

• Contenido: imágenes PNG o JPEG (raramente WebP).
• Uso: mapas base prerrenderizados, mapas estáticos, mapas históricos, ortofotos, etc.
• Formato declarado: campo de formato = png o jpg en la tabla de metadatos.
• Visualización: directamente compatible con la mayoría de librerías como Leaflet, OpenLayers o MapLibre, a través de un servidor de tiles (local o remoto).
• Ventajas:

  • Muy sencillo de implementar.
  • Renderizado consistente en todas las plataformas.
  • Sin procesamiento del lado del cliente.

• Limitaciones:

  • No hay interactividad nativa (no se puede hacer clic en la entidad).
  • Mayor peso: una imagen por mosaico.
  • Menos flexible en caso de cambios de estilo.

2.MBTiles vectoriales (VectorTiles)

• Contenido: datos vectoriales codificados en formato Mapbox Vector Tile (MVT, .pbf).
• Uso: mapas dinámicos, interactivos, multi-estilo (OpenStreetMap, mapas personalizados).
• Formato declarado: campo format = pbf en la tabla de metadatos.
• Visualización: requiere una biblioteca que soporte el renderizado vectorial (MapLibre GL, Mapbox GL JS, etc.).
• Ventajas :

  • Ligero: un solo archivo puede contener varios estilos.
  • Muy rápido de cargar con el motor de renderizado adecuado.
  • Interactivo: las entidades pueden interrogarse sobre la marcha.

• Limitaciones:

  • Requiere un renderizador del lado del cliente o un servidor como tileserver-gl.
  • Más complejo de generar.
  • Aún no soportado por todas las plataformas (Leaflet, por ejemplo, no lo soporta directamente).

En pocas palabras

Generación de archivos MBTiles: herramientas y flujos de trabajo

1.MBTiles Raster (imágenes)

Los mosaicos ráster se generan generalmente a partir de un mapa visualizado en un software SIG o en un motor de renderizado cartográfico. Estas son las principales herramientas:

Herramienta Descripción TipoQGISPlugin «Export as tiles» (o Processing → Generate XYZ tiles) Interfaz gráfica GDALgdal2tiles.py con la opción –mbtiles (desde GDAL 3. 1) Línea de comandos TileMill (antiguo) Creación de tiles PNG a través de Mapnik Interfaz gráficaMapTiler Desktop Interfaz completa para crear MBTiles (versión gratuita limitada) Interfaz gráficatippecanoe + rasterizar Flujo de trabajo híbrido: rasterizar aguas arriba si es necesario Línea de comandosMapProxy Genera dinámicamente y puede exportar a MBTiles Servidor/cache.

Caso de uso típico: mapa turístico, ortofoto, mapa escaneado.

2.MBTiles Mosaicos vectoriales

Los mosaicos vectoriales requieren codificación en PBF y corte en mosaicos según el estándar MVT (Mapbox Vector Tile). Esto requiere herramientas especializadas:

Caso de uso típico: mapa urbano interactivo, fondos personalizables, proyectos altamente interactivos.

Estructura interna de un archivo MBTiles

Un archivo .mbtiles es una base de datos SQLite que contiene mosaicos geográficos organizados según un esquema normalizado, que varía ligeramente entre los formatos raster y vectorial.

Tablas principales

mosaicos (o mapa + imágenes para vectores multiparte)

Nota: en formato vectorial, algunas implementaciones como tilemaker separan los metadatos de la imagen (imágenes) y las posiciones (mapa). En este caso, se crea una vista de tiles que los combina.

metadatos

Tabla clave-valor (clave = texto, valor = texto) que contiene información esencial para interpretar el archivo.

(optional) grids, grid_data, keymap

Utilizado para el formato UTFGrid, una forma obsoleta de interactividad en fondos rasterizados.

Notas importantes

• Las coordenadas de tile_row suelen estar invertidas dependiendo del sistema de tiles:

  • TMS (Tile Map Service): el origen está abajo a la izquierda.
  • XYZ (Web estándar): el origen está arriba a la izquierda.
  • La mayoría de los servidores y visualizadores modernos utilizan XYZ.

• El campo tile_data contiene :

  • Una imagen comprimida (png, jpg) para raster.
  • Un objeto PBF comprimido con zlib para mosaicos vectoriales.

• Para mosaicos vectoriales, el campo json en metadatos puede contener:

  • { «vector_layers»: [ { «id»: «buildings», «description»: «», «minzoom»: 12, «maxzoom»: 16, «fields»: { «name»: «String», «height»: «Number» } } ] }

Uso de MBTiles con Leaflet

Leaflet es una popular librería JavaScript para crear mapas interactivos. Soporta la integración de muchos tipos de fondos de mapa, incluyendo MBTiles. Estos son los pasos típicos y casos de uso para incrustar MBTiles en un mapa Leaflet.

1.Requisitos previos: Un servidor de teselas

Antes de utilizar MBTiles con Leaflet, necesitas configurar un servidor de tiles, ya que Leaflet no carga MBTiles locales directamente. Este servidor servirá los mosaicos como imágenes o en formato vectorial, accesibles a través de una URL.

Existen varias opciones para alojar MBTiles:

• TileStache
• Tileserver-GL
• Flask + Flask-tile (para una instalación ligera)
• Tileserver-php

Una vez configurado el servidor, puede distribuir los tiles vía HTTP, a los que Leaflet puede llamar para mostrarlos en el mapa.

2.Integración de MBTiles con Leaflet

A continuación se muestra un ejemplo sencillo de uso de un servidor de mosaicos con Leaflet para mostrar datos de un archivo .mbtiles:

Ejemplo con mosaicos rasterizados

a) Inicie el servidor de mosaicos

Vaya al directorio que contiene los mosaicos rasterizados.

php.exe -S localhost:8081

inicie el servidor de mosaicos

La siguiente página html muestra el contenido de los mosaicos del archivo countries.mbtiles situado en la subcarpeta tiles/. En el navegador debe introducir la dirección localhost:8081/nombre_página.html

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>Carte Mondiale</title>
    <link rel="stylesheet" href="https://unpkg.com/leaflet/dist/leaflet.css" />
    <style>
        html, body, #map { height: 100%; margin: 0; }
    </style>
</head>
<body>
<div id="map"></div>
<script src="https://unpkg.com/leaflet/dist/leaflet.js"></script>
<script>
    var map = L.map('map').setView([45, 2], 5);

    L.tileLayer('tileserver.php?file=tiles/countries.mbtiles&z={z}&x={x}&y={y}', {
        tileSize: 256,
        minZoom: 0,
        maxZoom: 6,
        attribution: '&copy; OpenStreetMap contributors'
    }).addTo(map);
</script>
</body>
</html>

El resultado es el siguiente:

3.Mosaicos vectoriales (MBTiles PBF)

Si está utilizando un archivo MBTiles vectorial (por ejemplo, generado por MapTiler o Mapbox), necesitará configurar Leaflet con un plugin que pueda interpretar mosaicos vectoriales. Leaflet.VectorGrid es uno de los plugins que pueden manejar mosaicos vectoriales en Leaflet.

Ejemplo con mosaicos vectoriales (PBF)

<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Carte Vectorielle MBTiles avec Leaflet</title>
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.7.1/dist/leaflet.css" />
    <script src="https://unpkg.com/leaflet@1.7.1/dist/leaflet.js"></script>
    <script src="https://unpkg.com/leaflet.vectorgrid@1.1.0/dist/Leaflet.VectorGrid.js"></script>
</head>
<body>
    <div id="map" style="height: 600px;"></div>

    <script>
        var map = L.map('map').setView([ -19.7, 63.35], 12); // Centré sur Rodrigues

        // Charger les tuiles vectorielles MBTiles
        L.vectorGrid.protobuf("http://localhost:8081/tileserver.php?file=tiles/map.mbtiles&z={z}&x={x}&y={y}", {
            vectorTileLayerStyles: {
                // Styles pour les tuiles vectorielles
                building: {
                    fillColor: 'blue',
                    weight: 1,
                    fillOpacity: 0.6
                },
                park: {
                    fillColor: 'green',
                    weight: 1,
                    fillOpacity: 0.6
                }
            }
        }).addTo(map);
    </script>
</body>
</html>

En este ejemplo, se utiliza el servidor Flask o Tileserver-GL para suministrar los mosaicos vectoriales, que Leaflet renderiza como vectores utilizando L.vectorGrid.

Sin embargo, esto no es tan sencillo como con los mosaicos rasterizados.

Simbología

La primera diferencia es que los mosaicos vectoriales, a diferencia de los rasterizados, no tienen simbología asociada a nivel de servidor. Por lo tanto, está obligado a definir la simbología a nivel del cliente html. Puede verlo en el código de ejemplo anterior:

vectorTileLayerStyles: {
                // Styles pour les tuiles vectorielles
                building: {
                    fillColor: 'blue',
                    weight: 1,
                    fillOpacity: 0.6
                },
                park: {
                    fillColor: 'green',
                    weight: 1,
                    fillOpacity: 0.6
                }
            }

Lo que también hay que saber es que no existe una simbología por defecto. Si una capa no tiene una definición de simbología en vectorTileLayerStyles, no se mostrará. En nuestro ejemplo, sólo se mostrarán edificios y parques, todas las demás capas (carreteras, etc.) serán ignoradas.

Dependencias

Leaflet.VectorGrid tiene varias dependencias que pueden complicar el funcionamiento del servidor local de tiles. Cuando mostramos un fichero .mbtiles convertido a .pbf a través de tileserver.php (por ejemplo), estamos llamando a tiles vectoriales en bruto desde un servidor PHP local, sin las cabeceras o codificaciones adecuadas. Ahora bien:

• Estos tiles requieren pbf.js (que puedes añadir: src=«https://unpkg.com/pbf@3.2.1/dist/pbf.js»)
• Pero también @mapbox/vector-tile para decodificar el contenido .pbf

Este último no está disponible como archivo .js que pueda utilizarse directamente en una página HTML: está escrito para Node.js o para un bundler moderno (Webpack, Vite, etc.).

Codificación

El código PHP por defecto en tileserver.php está configurado para manejar mosaicos rasterizados (imágenes PNG), pero no mosaicos vectoriales (.pbf).

Por lo tanto, tendrá que ajustar el archivo tileserver.php para servir mosaicos vectoriales (PBF):

Modificación de la cabecera Content-Type:
Para los mosaicos vectoriales, debe especificarse una cabecera Content-Type: application/x-protobuf, porque los mosaicos vectoriales son archivos en formato Protobuf (.pbf), no imágenes PNG.

Ejemplo de código PHP modificado para servir tiles vectoriales (PBF) :

<?php
// Ouverture de la base de données SQLite
$db = new SQLite3($_GET['file']);

// Extraction des coordonnées de la tuile
$z = (int) $_GET['z'];
$x = (int) $_GET['x'];
$y = (int) $_GET['y'];

// Conversion du système de coordonnées TMS vers XYZ
$y = (1 << $z) - 1 - $y;  // TMS flip

// Préparation de la requête pour extraire la tuile correspondante
$stmt = $db->prepare("SELECT tile_data FROM tiles WHERE zoom_level = :z AND tile_column = :x AND tile_row = :y");
$stmt->bindValue(':z', $z, SQLITE3_INTEGER);
$stmt->bindValue(':x', $x, SQLITE3_INTEGER);
$stmt->bindValue(':y', $y, SQLITE3_INTEGER);
$res = $stmt->execute();

// Si une tuile est trouvée
if ($row = $res->fetchArray()) {
    // Définir l'en-tête approprié pour les tuiles vectorielles Protobuf
    header('Content-Type: application/x-protobuf');
    
    // Retourner les données de la tuile
    echo $row['tile_data'];
} else {
    // Si aucune tuile n'est trouvée, renvoyer une erreur 404
    http_response_code(404);
}
?>

4.Escalabilidad y otros usos

Los MBTiles son especialmente útiles en situaciones en las que :

• El rendimiento es una cuestión importante, ya que los mosaicos se pueden distribuir eficientemente utilizando un servidor de mosaicos optimizado.
• Se desea distribuir un gran número de mosaicos fuera de línea o en un entorno sin conexión a Internet (mosaicos pregenerados almacenados en un único archivo).
• Los mosaicos se generan a partir de datos que cambian con frecuencia, y usted puede actualizarlos o sustituirlos con una interrupción mínima para los usuarios finales.

Conclusión

El formato MBTiles se adapta muy bien a las aplicaciones Leaflet, ya que ofrece una solución sencilla y eficaz para servir mosaicos geoespaciales, ya sean ráster o vectoriales. Con una instalación ligera y un servidor de mosaicos bien configurado, es fácil mostrar mapas de alto rendimiento y gestionar grandes cantidades de datos geoespaciales.

Si cet article vous a intéressé et que vous pensez qu'il pourrait bénéficier à d'autres personnes, n'hésitez pas à le partager sur vos réseaux sociaux en utilisant les boutons ci-dessous. Votre partage est apprécié !

Atilio Francois