DerekEllis at 02:19, 24 December 2021

2021-12-24T02:19:53Z

DerekEllis: Add content

2021-12-23T04:11:22Z

Add content

Show changes

DerekEllis: Initial edit

2021-12-14T02:40:40Z

Initial edit

New page

== Overview ==

Basemaps play an important role in giving geographic context to a map,
however they can be hard to come across and are typically only available under a copyright or license that makes the unusable for many projects.
The styling of a basemap can also affect the aesthetic of a map, however the appearance of basemaps is generally controlled by the original creator of the basemap.

This tutorial will show how to create a custom basemap using open data, how to apply a customized style to the basemap, and how to use the basemap in a mapping application.

== Prerequisites ==

This tutorial will require some basic command line use (running commands, changing directories) and will be done in a Linux environment, however the same steps can be performed on other operating systems like Windows and macOS as well.

The following tools will need to be installed:


* NodeJS
* Docker
* docker-compose
* git
* Osmium
* tileserver-gl-light

== Vector Tiles ==

Tilesets are a way of storing geographic data that has been split up into a uniform grid of tiles, and pre-processed to be displayed at preset zoom levels.
This pre-processing makes it really easy for a "tileserver" to serve only the relevant data for the current view and zoom of a map viewport, which is far more efficient than trying to load an entire raw dataset.
A tileset can contain vector or raster data, however we will be creating a tileset of vector data.


Our vector data source will be OpenStreetMap which makes its data available under the Open Database License (ODbL).



=== Generating Tiles ===

To generate our own vector tiles, we will be using the OpenMapTiles project which provides and open-source tool for generating tilesets from OpenStreetMap data.

To install OpenMapTiles, run the following command, and then change into the openmaptiles directory:
<syntaxhighlight lang="bash">
git clone https://github.com/openmaptiles/openmaptiles.git
cd openmaptiles
</syntaxhighlight>

A "quickstart" script is provided which can be run to quickly generate tiles. By default, it will download data for, and generate a tileset of Albania.
By providing the name of a specific region ([https://github.com/openmaptiles/openmaptiles/blob/master/QUICKSTART.md from a set list of regions]), the script will generate tiles for the specified region instead.
The tileset data will be stored in the <syntaxhighlight inline>data</syntaxhighlight> directory, under the OpenMapTiles project.

<syntaxhighlight lang="bash">
./quickstart.sh # Generate tileset of Albania

./quickstart.sh canada # Generate tileset of Canada
./quickstart.sh quebec # Generate tileset of Québec
</syntaxhighlight>

This process can be very slow for large regions like Canada or Québec however, so we will see how to create smaller OpenStreetMap datasets for OpenMapTiles to convert.

=== Creating Custom OpenStreetMap Data Extent ===

An OpenStreetMap dataset contains raw high detail vector data, which results in very large data files.
For example, Canada alone contains 2.8GB worth of vector data which is both a lot to download, but also a lot to process.
Most sources for downloading OpenStreetMap data will only allow a very small extract of data to be downloaded, but some sources like [https://download.geofabrik.de/ Geofabrik] provide larger pre-extracted downloads.
Geofabrik has per-province extracts, which can be more manageable to work with.

Let's say that for this tutorial we want to create a basemap of the Ottawa-Gatineau region, which happens to span across both Ontario and Québec.
Unfortunately this means that the Geofabrik extracts would split our region across the provincial border, but we can combine the two extracts using a tool called [https://osmcode.org/osmium-tool/ Osmium].
The commands below will download and merge the two extracts.
We can also go one step further and also use Osmium to extract a much smaller extent of just the Ottawa-Gatineau area, and by leaving out the rest of Ontario and Québec we cut the merged dataset down from 1.2GB to just 48MB.

<syntaxhighlight lang="bash">
# Download provincial extracts
wget https://download.geofabrik.de/north-america/canada/ontario-latest.osm.pbf
wget https://download.geofabrik.de/north-america/canada/quebec-latest.osm.pbf

osmium merge ontario-latest.osm.pbf quebec-latest.osm.pbf -o merged.osm.pbf

# Extract the National Capital Region
osmium extract -b -76.2616,45.1249,-75.1726,45.6620 merged.osm.pbf -o ncr.osm.pbf
</syntaxhighlight>

=== Generating Tiles (cont.) ===

Before generating any more tiles, we need to make one adjustment to the default configuration of OpenMapTiles to allow it to generate more tile zoom levels.
By default it will only generate 7 levels, as this is much quicker and can be used for creating previews of tilesets.
Open the <syntaxhighlight inline>.env</syntaxhighlight> file from the OpenMapTiles project and change the <syntaxhighlight inline>MAX_ZOOM</syntaxhighlight> variable to read <syntaxhighlight inline>MAX_ZOOM=14</syntaxhighlight>.
This tells the tool to generate the higher-detail zoom levels.

Now with the <syntaxhighlight inline>ncr.osm.pbf</syntaxhighlight> inside of the OpenMapTiles <syntaxhighlight inline>data</syntaxhighlight> directory, we can now run the following commands to generate a tileset for our extent.

<syntaxhighlight lang="bash">
# ncr refers to ncr.osm.pbf, created in previous section
make generate-bbox-file area=ncr

./quickstart.sh ncr
</syntaxhighlight>

After running, this will produce a <syntaxhighlight inline>tiles.mbtiles</syntaxhighlight> file in the <syntaxhighlight inline>data</syntaxhighlight> directory containing our tileset.

== Serving Tiles ==

Now that we have generated our map tiles, we want to serve them so that they can be used by a mapping application.
We will do this with <syntaxhighlight inline>tileserver-gl-light</syntaxhighlight>
After running the following command, the server can be accessed at [http://localhost:8080 http://localhost:8080].

<syntaxhighlight lang="bash">
tileserver-gl-light ./data/tiles.mbtiles
</syntaxhighlight>

The homepage of the tileserver includes a link that can be used to preview the tileset.
By zooming into our extent of Ottawa-Gatineau we can see the detailed vector tiles being loaded in. Areas outside of the extent will be blank, since we didn't include that data when generating the tiles.

== Using Vector Tiles in QGIS ==

Vector tiles in this format can be consumed by many tools and libraries, but we will demonstrate their use in QGIS here.
MapTiler develops a plugin for QGIS, also called MapTiler, which enables the use of vector tiles in QGIS.

To install the plugin, in QGIS navigate to the Plugins > Manage and Install Plugins... menu. In the search bar, enter "MapTiler", select the plugin that turns up in the search results, and install the plugin.
Once installed, a new "MapTiler" dropdown will be added to the QGIS Browser panel.
Expanding the dropdown shows a list of preset vector tile services that can be added, however they require a MapTiler access key.

To add our own tile server, we can right click on the MapTiler dropdown and select "Add a new map...".
The popup will default to adding a new map from URL, where we can give our map a name, and then enter the URL to the tile server's style JSON.

We can then add the new map as a layer in our QGIS project.

The plugin treats the vector tiles as proper vector data, meaning that it can be queried like any other vector features in QGIS.
When producing map layouts, the vector data can even be exported to vector graphics formats like SVG and PDF.

== Styling the Map ==

By default the tile server we created renders the vector data in a fairly plain-looking style.
Perhaps we would like to change the colours to fit our desired aesthetic, or to emphasize certain features, or even to add and remove some features from the map altogether.


The [https://docs.mapbox.com/mapbox-gl-js/style-spec/ Mapbox GL style specification] is used to customize the style of vector tiles.
A style is a JSON document that specifies (among other things), a list of layers to be rendered.
These layers derive their data from the vector data source we produced earlier, but can be filtered to only display certain features from the source.
Those features can they have different layout and paint properties applied to them, and the styling can even be set up to change depending on a feature's data properties.

It is possible to write a style directly as a JSON document, however it can be complicated.
Instead, we will use the [https://maputnik.github.io/editor Maputnik editor], which is an open-source web app for editing map styles.
The editor shows the current style in a viewport, and has panels on the left which list the style's layers, and the different styling properties applied to a selected layer.



=== Adding / Removing Layers ===
Layers take some or all features from a data source (our vector tiles in this case) and apply some layout and paint properties to those features which dictate how they will be rendered.
A layer can select which features will be included by specifying a source layer or filter property. A data source can have multiple data layers, and the filter can be used to further refine the selection using the filter property.

For example:

<syntaxhighlight lang="json">
{
"id": "road_secondary_tertiary",
"type": "line",
"source": "openmaptiles",
"source-layer": "transportation",
"filter": [
"in",
"class",
"secondary",
"tertiary"
],
"layout": {},
"paint": {}
}
</syntaxhighlight>

This defines a layer that takes the features from the <syntaxhighlight inline>transportation</syntaxhighlight> source layer in the <syntaxhighlight inline>openmaptiles</syntaxhighlight> data source,
and then filters specifically for features (roads in this case) that are in the secondary and tertiary road class.

The list of all available source layers and properties are defined in the [https://openmaptiles.org/schema/ OpenMapTiles Vector Tile Schema].

=== Layout and Paint properties ===


Layout and paint properties define how features in a certain layer will be displayed. These properties are specified in the [https://docs.mapbox.com/mapbox-gl-js/style-spec/ Mapbox Style Specification].

@@ Line 337: / Line 337: @@
 <!-- Image: Vector Tiles in QGIS -->
 [[File:QGISVectorTile.png|500px]]
+== Licensing Considerations ==
+Remember that the Open Database License requires that OpenStreetMap contributors are credited when using data or datasets that are derived from OpenStreetMap data.
+In addition, any use of the vector tiles that are created using OpenMapTiles [https://openmaptiles.org/docs/generate/generate-openmaptiles/ must also credit OpenMapTiles].
+An example attribution of both: © OpenMapTiles © OpenStreetMap contributors
 == Conclusion ==

Creating Custom Basemaps with Vector Tile Servers - Revision history

DerekEllis at 02:19, 24 December 2021

DerekEllis: Add content

DerekEllis: Initial edit