Exporting rasters to Mbtiles using GDAL

Web maps are generally made up of many small, square images called tiles, which are placed side by side in order to create the illusion of a very large seamless image [for a good explanation, see here].

Tiled based maps can be made up of many tiles. Loading all those tiles would be inefficient and slow. That is where the MBtiles, developed by Mapbox, come in. The MBtiles specification is an efficient format for storing millions of tiles in a single SQLite database.

I have written before about Tilemill, a great tool to create great looking interactive maps. Since then more tools have come available to create MBtiles. Arguably most important is that starting with version 1.1, GDAL offers read support for rasters in MBtiles format, while with GDAL 2.1 the MBtiles driver has creation and write support for MBtiles datasets. This is especially important given that the GDAL library underlies nearly all major open source and many proprietary  geospatial projects, such as QGIS, GRASS GIS, ArcGIS and Google Earth.

This means that it is possible for all these software tools, in theory at least, to export raster layers to MBtiles. And QGIS and GRASS GIS at least both offer front-ends for the GDAL functions mentioned below. As a side note, QGIS also has the QTiles add-on that allows one to export raster layers as MBtiles. It works great on smaller rasters, but you may want to go out for a cup of coffee if used for larger raster layers.

Here I will however illustrate how you can use GDAL directly and gdal2mbtiles to convert your raster layer to a tiled raster in MBtile format.

Method 1 – GDAL functions

Preparation: Depending on your input data, you may need to ‘expand’ your layer from a 1 band with colour table to a layer with 3 (RGB) or 4(RGBA) bands. This can be done with the gdal_translate function. You furthermore need to reproject your layer to Web Mercator projection (EPGS: 3857), which can be done with the gdalwarp function.

gdal_translate -expand rgba mymap1.tif mymap2.tif
gdalwarp -t_srs EPSG:3857 -r near mymap2.tif mymap3.tif

Export: Converting a raster layer to a MBtiles map takes two steps. First, use gdal_translate to convert your raster layer to a tiles layer (see here for MBtile specific options). This will only create the highest zoom level. Gdal_translate determines this automatically based on the image resolution. I am not sure if/how you can set the desired maximum zoom level yourself (please leave a comment if you know how). Next, use the gdaladdo function to build overview images, i.e., the lower zoom levels.

gdal_translate -of mbtiles mymap3.tif mymap.mbtiles
gdaladdo -r nearest mymap.mbtiles 2 4 8 16

This method is very fast and easy enough. I ran into the issue, however, that once in a while, the process fails with an error about the database being locked [ERROR 1: Failure when inserting partial tile (row=843,col=1489) at zoom_level=11 : database is locked]. I need to find out where the problem lies, but in the meantime, I am using the next tool, gdal2mbtile.

Method 2 – gdal2mbtile

The gdal2mbtile application can download from Github. The tool combines the gdal2tiles (part of GDAL) and mbutil tools. The command line interface (CLI) is almost the same as that of gdal2tiles. Like above, you first may need to convert your layer to a RGBA layer and project it to the Web Mercator projections. Next, you simply run (replace ‘path’ with the path to the gdal2mbtiles library):

/path/gdal2mbt mymap3.tif -z 4-12 -w none -o xyz mymap.mbtiles

This will create a mbtile raster with 4-12 zoom levels. It runs, for me at least, flawlessly and very fast.

Some final notes

Tilemill is still a great tool, especially as it is one of the few tools I know that makes it easy to create interactive MBtiles (i.e., with UTFgrid). Unfortunately, the project is not actively developed any more it seems, and I had problems installing it on Ubuntu 16.04. Luckily I found a fork, Tileoven,that I could install without problems. Give it a try if you, like me, cannot install Tilemill.

There is actually several other project on Github with the name gdal2mbtiles. Some haven’t seen much activity in the last few years, but this one looks interesting, especially because it seems to offer some more output options. I’ll probably try that one out soon as well. If you have tried it out already, let me know.