.. _plugins-mbtiles:

mbtiles
=======

The *mbtiles* plugin provides the ability to load maps from tiles
(:cite:t:`tiles`) in a SQLite database or tile servers such as
OpenStreetMaps :cite:p:`osm-servers`.
Map tiles are used, e.g., by the high-resolution maps provided by |gempa|.
The plugin is shipped with the gempa package *mapprojections*.

.. figure:: /base/media/scmv_mbtiles.png
   :width: 50%
   :align: center

   High-resolution map by |gempa|.

.. note::

   Different maps can be loaded depending on geografic location and zoom level
   with the plugin :ref:`plugins-tscombine` which also ships with the
   *mapprojections* package.


Setup
------

#. Install the SQLite Qt database driver.
#. Add the *mbtiles* plugins to global configuration (:file:`global.cfg`)

   .. code-block:: properties

      plugins = ${plugins}, mbtiles

#. Configure the map source, type and format:

   * for files in a SQLite database files:

     .. code-block:: properties

        map.location = /home/data/maps/high-resolution-gempa-maps.mbtiles
        map.type = mbtiles

   * for map tiles from a tile server (:cite:t:`osm-servers`). You may add a
     tile cache for storing and accessing downloaded tiles on disc:

     .. code-block:: properties

        map.type = osm
        map.location = http://[server]]/%l/%c/%r.png
        map.osm.maxLevel = 10

        map.osm.cacheDir = /home/data/maps/OSM
        map.osm.cacheDuration = -1


Module Configuration
--------------------

.. confval:: map.type

   Values: ``mbtiles,osm``

   Type: *string*

   The store implementation.

.. confval:: map.osm.tileSize

   Default: ``256``

   Unit: *px*

   Type: *int*

   Edge length of the square tiles received from the server.

.. confval:: map.osm.maxLevel

   Default: ``10``

   Type: *int*

   Maximum available/allowed tile level. The OpenStreetMap servers typically
   serve data up to level 19.

.. confval:: map.osm.cacheDir

   Type: *string*

   Path of an optional cache directory. If specified downloaded tiles will we
   cached to speed up requests and to save network bandwidth.

.. confval:: map.osm.cacheDuration

   Default: ``86400``

   Unit: *s*

   Type: *int*

   Number of seconds a cached tile is valid. Cache files older than the
   specified number of seconds are reloaded from the tile server upon request.
   Use a negative value to indicated an unlimited cache duration.