Creating Shortbread Vector Tiles

Creating Shortbread vetor tiles consists of a couple of steps. This page provides an overview about the tile generation process. It consists of the following steps.


In order to build vector tiles, you have to provide the following dependencies:

Ubuntu/Debian: apt install curl unzip gdal-bin

Tilemaker Installation

The Shortbread vector tile schema requires a special feature of Tilemaker (sorting features in a layer by a float number). Therefore, Tilemaker has to be compiled with FLOAT_Z_ORDER set to any value.

Clone and compile Tilemaker:

git clone --branch v2.4.0
cd tilemaker

Installation of Tilemaker is described in the Tilemaker Readme as well.

Clone Schema Repository

Clone the Git repository of the vector tile schema from Github:

mkdir shortbread-tilemaker
git clone shortbread-tilemaker

Download Ocean Shape Files

The vector tile schema retrieves ocean polygons fro pre-processed ocean polygon shape files by A script is provided to download and update them. It will write the shape files to the subdirectory data.

Tilemaker requires shape files in geographic coordinates (EPSG:4326) but the simplified shape file is provided in Web Mercator (EPSG:3857) only. Therefore, GDAL’s ogr2ogr is used to transform the shape file.

cd shortbread-tilemaker

Download OpenStreetMap Raw Data

Tilemaker needs raw OpenStreetMap data in .osm.pbf format as input. You can download it from

Please try with a small extract first before you try to load the complete world.

Generate Vector Tileset

Generating vector tiles seems to be pretty simple but there are some show stoppers to keep in mind:

Run Tilemaker (this command should be executed from the shortbread-tilemaker directory):

tilemaker --bbox -180,-86,180,86 --input planet-latest.osm.pbf --store tilemaker-cache.dat --config config.json --process process.lua --output output_directory/

In February 2022, a server with a AMD EPYC 7452 32-Core Processor (2.35–3.35 GHz), 512 GB RAM, cache on NVMe and output to a loop-mounted hard disk drive (RAID 1) took 16:15 hours and needed up to 358 GB RAM.


z_order is limited to 1 byte signed integer”

Error message:

lua runtime error: z_order is limited to 1 byte signed integer.
terminate called after throwing an instance of 'kaguya::LuaTypeMismatch'
  what():  type mismatch!!

Reason: Your version of Tilemake was compiled without the flag FLOAT_Z_ORDER.

Solution: Recompile Tilemaker using make clean && make CONFIG=-DFLOAT_Z_ORDER.