Preparing offline map packages

This page may require some technical knowledge about geospatial data. If the content of this page feels unfamiliar to you, get someone acquainted with geographic information systems (GIS) to help you.

If you have gone through all the below steps and your offline maps are still not showing up, you might be facing a commonly encountered issue described here: Offline map tiles are not showing up

For offline or mesh network usage, Terrastories can load a background map using a locally hosted map tileset and style, instead of a map from Mapbox Studio. This requires you to provide your own locally hosted map tiles and style.

By default, Terrastories provides a set of open-license offline map tiles, generated through the OpenMapTiles API. These tiles cover the entire world, but are only compiled up to zoom level 8 (roughly the extent of a small country like Rwanda, Costa Rica, Slovenia or Bhutan). Once you zoom in past zoom level 8, no further level of detail will show.

However, you can also provide your own map tiles, which have to be in a mbtiles or a pmtiles format , alongside any map fonts (glyphs), sprites, and a style.json that defines how the map tiles will be visualized and styled on a map canvas.

How to generate or convert map tiles

Map tiles can be generated using existing utilities, or converted from standard geospatial data (Shapefile, GeoJSON), in several ways.

• Generate tiles using QGIS: The open-source GIS software QGIS has several tools for generating MBTiles in both raster and vector format. Generate XYZ tiles (MBTiles) can be used to create raster tiles of all of the content on your map canvas; this may also include XYZ Tiles from services such as OpenStreetMap, Bing, and Google Satellite. Generate Vector Tiles (MBTiles) can be used to create vector tiles from one or more vector layers. You can then further style these vector tiles in your style.json file.

  • The page Generating map files in .mbtiles format for the experimental Background Maps feature in the Mapeo support materials has a visual, step-by-step guide for using QGIS to generate raster tiles.

• Generate tiles using mapgl-tile-renderer: The mapgl-tile-renderer tool can be used to generate rasterMBTiles from various sources including Bing Satellite, Esri World Imagery, Google Earth, and more, with an optional OpenStreetMap overlay.

• Convert tiles using tippecanoe: There is also a command line tool called tippecanoe which can be used to generate vector MBTiles or PMTiles from Esri Shapefiles and other formats: guide.

• Convert tiles using mbutil: If you already have tiles in a different format (such as xyz), you can use a Node command line tool called mbutil to convert them to MBTiles. Please see our xyz to mbtiles conversion repository or this page Generating map files in .mbtiles format for the experimental Background Maps feature in the Mapeo support materials for more information.

Once generated, place the tiles in the map/data/ directory.

Compiling a custom style (style.json)

Map styles (per the style.json schema) defines the visual appearance of a map: what data to draw on the map canvas, the order in which layers are displayed, and how to style the data when drawing it. Mapbox provides a helpful guide with all of the possible style parameters, but it's generally useful to download an existing style.json file and modify it to suit your needs.

Using Mapbox (for vector)

One of the easiest ways to build a style.json file is by uploading and styling your data on Mapbox Studio and downloading the style.json file from there, in the following way:

• Design your map in Mapbox Studio. Mapbox provides extensive documentation and tutorials on using Studio here.

• When you are done designing your map in the Mapbox Studio environment, click "Share" and then download the Map style ZIP file.

• Unzip the file, and extract the style.json and place it in tileserver/data/styles.

• Next, you will need to make some changes. The style.json from Mapbox will be referring to an online URL for the map sources. You need to change this to refer to the local MBTiles. Change sources > composite > url to the following format: "url": "mbtiles://mbtiles/name.mbtiles". (Here, name is just an example; it can be called whatever you want, so long as the filename is the same.)

Importantly, the layer names referenced in styles and MBTiles have to match, in order for the tiles to receive a style property. It may be necessary to edit the layer names in style.json to reflect the names of the spatial data in the MBTiles file.

Note: it is also possible to use Maputnik, the open-source visual editor for the Mapbox style specification, to style your MBTilesdata.

Raster tiles

If you have raster tiles that you want to load in Terrastories, those will need to defined differently from the vector tiles above. In sources, create a new source definition with url pointing to the raster MBTiles in the same format as above, and with type set to raster. Then, in layers, create a map object with your id of choice, type set to raster, and source set to the name of your raster tiles as defined in sources. Here is an example style.json file which only loads a raster MBTiles:

{
  "version": 8,
  "name": "Terrastories offline raster map",
  "sources": {
    "terrastories-raster-mbtiles": {
      "type": "raster",
      "url": "mbtiles://tiles.mbtiles" // or pmtiles
    }
  },
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": {"background-color": "hsl(47, 26%, 88%)"}
    },
    {
      "id": "terrastories-raster-mbtiles",
      "type": "raster",
      "source": "terrastories-raster-mbtiles"
    }
  ],
}

If you want, you can add additional tile sources (vector as well as raster), and place your raster tile layer underneath vector layers. This is a good way to have an offline satellite imagery basemap with vector data (points, lines, polygons, and labels) overlaid on top of it.