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.
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
mbtilesformat, and provided alongside any map fonts, sprites, and a
style.jsonfile where the
mbtilesfile is placed on a map canvas.
Our setup script, which detects if you already have a
style.jsonfile in your
tileserver/datadirectory, and if not, downloads the default offline tiles for you.
MBTilescan be generated from standard geospatial data (Shapefile, GeoJSON) in several ways.
- The open-source GIS software QGIS has several tools for generating
MBTilesin 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
- 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
tippecanoewhich can be used to generate vector
MBTilesfrom 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 called
mbutilto 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
tileserver/data/mbtiles/directory, with the right filename as referenced by
Working with custom styles
Map styles (per the
style.jsonschema) 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.jsonfile and modify it to suit your needs. One of the easiest ways to build a
style.jsonfile is by uploading and styling your data on Mapbox Studio and downloading the
style.jsonfile from there, in the following way:
- In the Mapbox Studio environment, click "Share" and then download the Map style ZIP file.
- Unzip the file, and extract the
style.jsonand place it in
- Next, you will need to make some changes. The
style.jsonfrom Mapbox will be referring to an online URL for the map sources. You need to change this to refer to the local
urlto the following format:
"url": "MBTiles://MBTiles/name.MBTiles". (Here,
nameis just an example; it can be called whatever you want, so long as the filename is the same.)
Importantly, the layer names referenced in
MBTileshave to match, in order for the tiles to receive a style property. It may be necessary to edit the layer names in
style.jsonto reflect the names of the spatial data in the
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
urlpointing to the raster
MBTIlesin the same format as above,
256. Then, in
layers, create a map object with your
sourceset to the name of your raster tiles as defined in
sources. Here is an example:
You can define multiple
mbtilessources (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.