Shortbread schema

• Basic, lean, general-purpose vector tile schema for OSM data
• CC0 licensed
• shortbread-tiles.org

History

• Created for Geofabrik by Thomas Skowron, Christine Karch, Amanda McCann and Michael Reichert
• Experimental downloads by Geofabrik, Mapnik style
• Versatiles maps with three styles (Unlicence/CC0)
• Handed over to community (PSC) at Karlsruhe Hack Weekend 2/2024
• osm.org vector tiles with minutely updates

Schema specification

https://shortbread-tiles.org/schema/1.0/

Schema overview

• Water
  • ocean, water_polygons, water_lines, water_lines_labels,…
• Countries, States, Cities
  • boundaries, boundary_labels, place_labels
• Land Use, Land Cover, Buildings
  • land, sites, buildings, addresses
• Streets and Transport
  • streets, street_labels, bridges, aerialways, ferries, …
• Points of interest
  • public_transport, pois

Shortbread styles

Versatiles Colorful

colorful, full featured map

Versatiles Graybeard

gray, full featured map

Versatiles Neutrino

light basemap

Viewer

• MapLibre GL
• OpenLayers (ol-mapbox-style)
• Leaflet (maplibre-gl-leaflet plugin)
• deck.gl (MVTLayer), kepler.gl

Tile creation workflows

PBF → Vector tiles

• tilemaker (tilemaker.org)
• Planetiler (github.com/onthegomap/planetiler)

PBF → DB → Vector tiles

• osm2pgsql (osm2pgsql.org)
  • BBOX (t-rex) (www.bbox.earth)
  • Tilekiln (github.com/pnorman/tilekiln)

Tile storage

• Files / S3
• MBTiles + tile service
• PMTiles
• DB cache + tile service

tilemaker

• Configs for OpenMapTiles and Shortbread schema
• JSON configuration with Lua scripts
• Output formats: MBTiles, PMTiles
• No diff support

Planetiler

• Configs for OpenMapTiles and Shortbread schema
• YAML configuration or Java application
• Output formats: MBTiles, PMTiles
• No diff support
• Extremely fast: Planet in 22m

osm2pgsql

• Flex mode: configuration with Lua scripts
• Osm2pgsql Themepark with Shortbread config
• osm2pgsql-gen for generalization in database
• osm2pgsql-replication for incremental updates
• Config generation for tile servers

BBOX

• Generate and serve vector tiles
• OGC API services
• Raster and vector tiles
• PostGIS, MBTiles, PMTiles, S3
• Non-Mercator tile grids
• Successor of t-rex tile server

Tilekiln

• Generate and serve vector tiles
• Data source: PostGIS
• Caching tiles in PostgreSQL
• Quickstart

Customize Shortbread

Use cases

• Custom style
• Additional POIs
• Route relations
• More tags for special objects
• Additional tags for streets or buildings
• Other / more languages

Styling

Mapbox / MapLibre GL JSON: https://maplibre.org/maplibre-style-spec/

{
  "source": "birddata",
  "source-layer": "change_increase",
  "type": "circle",
  "paint": {
    "circle-radius": {
      "property": "code",
      "stops": [
        [1, 5],
        [2, 10],
        [3, 15]
      ]
    },
    "circle-stroke-color": "#000000"
  }
},

Style editor

Maputnik Editor (maplibre.org/maputnik)

Versatiles Styler

maplibre-versatiles-styler

Extending Shortbread

• tilemaker config (JSON, Lua)
• Planetiler config (YAML, Java)
• osm2pgsl config (Lua)

Tileset combinations

• Extended base map tiles
  • No additional tiles
  • Can break base map styles
  • Selfhosting required
• Additional tilesets
  • Additional tile source in style
  • No easy relation to base map tiles
  • Potential duplication of data

Server-side combination

• Vector tiles can be concatenated by server
• Requires a service
• Not supported by all tile servers
• Caching more difficult

Publish custom tiles

PMTiles, style and sprites

# Generate Shortbread tiles
docker run --rm --user=$UID -v $PWD/data:/data ghcr.io/onthegomap/planetiler shortbread.yml \
  --download --area=liechtenstein --output=/data/shortbread.pmtiles
# Download Versatiles Styles + Assets
mkdir -p styles assets/sprites
wget -O - https://github.com/versatiles-org/versatiles-style/releases/latest/download/styles.tar.gz | tar xz -C styles
wget -O - https://github.com/versatiles-org/versatiles-style/releases/latest/download/sprites.tar.gz | tar xz -C assets/sprites
# Replace tile source with PMTiles URL
jq '.sources."versatiles-shortbread".url="pmtiles:///shortbread.pmtiles" | del(.sources."versatiles-shortbread".tiles)' \
   styles/colorful.json > styles/colorful-pmtiles.json
# Make sprite URL relative
sed --in-place -e 's!https://tiles.versatiles.org/assets/sprites!/assets/sprites!g' styles/*.json

Viewer HTML

index.html:

<!DOCTYPE html>
<html>
  <head>
    <title>MapLibre Viewer</title>
    <script src='https://unpkg.com/maplibre-gl@4.5.0/dist/maplibre-gl.js'></script>
    <link href='https://unpkg.com/maplibre-gl@4.5.0/dist/maplibre-gl.css' rel='stylesheet' />
    <script src="https://unpkg.com/pmtiles@3.0.6/dist/pmtiles.js"></script>
    <style>
        body { margin: 0; }
        #map { height: 100vh; width: 100vw;}
    </style>
  </head>
  <body>
    <div id="map"/>
    <script>
      let protocol = new pmtiles.Protocol();
      maplibregl.addProtocol("pmtiles", protocol.tile);
      var map = new maplibregl.Map({
        container: 'map',
        style: 'styles/colorful-pmtiles.json'
      });
    </script>
  </body>
</html>

Deploy and serve

# Upload to site supporting HTTP Range Requests

scp -r . example.com:


# Or deploy to a hosting provider like Github pages

Example

https://maps.bbox.earth/

MapLibre with Shortbread PMTiles.