Comment on page
Preparing offline maps
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 an open-source map tileserver called TileServer-GL and locally hosted map tiles, instead of a map from Mapbox. This requires you to provide your own locally hosted map tiles.
Terrastories does provide a default 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.
When you set up Terrastories for 🛖 Hosting Terrastories offline as a "Field Kit" or 🖧 Hosting Terrastories on a mesh network, you will be given the option to use these default offline map tiles. However, you can also provide your own map tiles, which have to be in a
mbtiles
format, and provided alongside any map fonts, sprites, and a style.json
file where the mbtiles
file is placed on a map canvas.
Our setup script, which detects if you already have a
style.json
file in your tileserver/data
directory, and if not, downloads the default offline tiles for you.MBTiles
can be generated from standard geospatial data (Shapefile, GeoJSON) in several ways.- 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 yourstyle.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.
- There is also a command line tool called
tippecanoe
which can be used to generate vectorMBTiles
from Esri Shapefiles and other formats: guide. - If you already have tiles in a different format (such as
xyz
), you can use a Node command line tool calledmbutil
to convert them toMBTiles
. 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
MBTiles
in the tileserver/data/mbtiles/
directory. The source for the
MBTiles
to be used in your map style is defined in tileserver/data/config.json
. If your MBTiles
is not called tiles.mbtiles
, you will need to change the filename here: "data": {
"terrastories-map": {
"mbtiles": "mbtiles/tiles.mbtiles"
}
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. 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 intileserver/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 localMBTiles
. Changesources
>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
MBTiles
data.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, type
set to raster
, and tileSize
to 256
. 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://{terrastories-map}",
"tileSize": 256
}
},
"sprite": "sprite",
"glyphs": "{fontstack}/{range}.pbf",
"layers": [
{
"id": "background",
"type": "background",
"paint": {"background-color": "hsl(47, 26%, 88%)"}
},
{
"id": "terrastories-raster-mbtiles",
"type": "raster",
"source": "terrastories-raster-mbtiles"
}
],
"id": "basic"
}
If you want, you can add additional
mbtiles
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.