How to develop your own style of OpenMapTiles with your favorite editor?

How to develop your own style of OpenMapTiles with your favorite editor? Taro Matsuzawa (@smellman) Taro Matsuzawa - State of the Map 2024

Self introduction Georepublic Japan GIS Engineer. Director of OpenStreetMap Foundation Japan, OSGeo.JP. Sub-President of Japan Unix Society. Lead of United Nations OpenGIS/7 core. Music: Breakcore 2

My works OSS Contribution: MapLibre GL JS, OpenLayers-ext, OpenMapTiles, Redmine Plugin, React Native Libraries and others. See: https://github.com/smellman I manage redmine based project management system. https://www.lobsta.org/ Create some applications with OpenStreetMap. Create some applications using Point Cloud data. Work with Python, Ruby and TypeScript. Server administrator of OpenStreetMap Japan. 3

• https://github.com/smellman
• https://www.lobsta.org/

About Georepublic GIS developer company in Japan. Famous as founder company of pgRouting. Supporter of OpenStreetMap Foundation Japan, and OSGeo.JP. 4

Noto clime in Japan Thanks for support to Noto Clime in Japan. HOTOSM and global community support to Noto Clime in Japan. 5

Today’s topic 1. Introduction of OpenMapTiles schema. 2. Introduce of Charites to use your favorite editor. 3. Introduce of other tools to compile JSON format for MapLibre GL. 6

Introduction of OpenMapTiles schema 7

OpenMapTiles https://openmaptiles.org/ OpenMapTiles is generate system of vector tiles from “selected OpenStreetMap tags”. 8

• https://openmaptiles.org/

“Selected OpenStreetMap tags” OpenMapTiles doesn’t deliver all tags in OpenStreetMap. We call “schema”. https://openmaptiles.org/schema/ <way building=yes building:levels=3 >...</way> OpenStreetMap layer:building render_height=10.98 OpenMapTiles Vector tile 9

• https://openmaptiles.org/schema/

Layers ● ● ● ● ● ● ● ● ● ● ● aerodrome_label aeroway boundary building housenumber landcover landuse mountain_peak park place poi ● ● ● ● ● transportation transportation_name water water_name waterway 16 layers available. 10

tile.openstreetmap.jp The vector/raster tile server. Supports Planet We put PMTiles in https://tile.openstreetmap.jp/static ● ● Planet OSM vector tile Overture Maps vector tile 11

• https://tile.openstreetmap.jp/static

Introduce of Charites to use your favorite editor 12

To edit MapLibre GL Style To edit MapLibre GL Style, there are some option. 1. Edit style.json on your editor 2. Use Maputnik 3. Use Charites and your editor 13

Edit style.json on your editor You can write your own style via editor. I recommend to use Visual Studio Code with extension by Kanahiro Iguchi. https://github.com/Kanahiro/maplibre-vscode-extension 14

• https://github.com/Kanahiro/maplibre-vscode-extension

But… Sometime JSON provides as minify. Difficult edit one file with too many layers. 15

Use Maputnik https://maplibre.org/maputnik/ GUI editor for MapLibre GL Style. Easy to use. 16

• https://maplibre.org/maputnik/

But… Maputnik is difficult to replace strings(ex. Font name, color values) like the editor. Currently Maputnik does not support PMTiles. Require some operations if you use version control system(ex. git). Solution: Run Maputnik in localhost. 17

Use Charites and your editor Charites is a command line tool for support editing your own style. Charites manages your style as YAML format with separated layers. YAML format is easy to read than JSON format. Also, Charites supports PMTiles. Validate your style automatically. 18

Charites workflow convert style.json Charites style.yml serve build layers/backgroun d.yml layers/poi.yml layers/… 19

How to install Install Node JS version 20 higher. Run following command in your terminal: npm install -g @unvt/charites 20

Convert your style to YAML format Run following command: wget https://tile.openstreetmap.jp/styles/osm-bright/style.json charites convert style.json 21

Start to serve your style Run following command: charites serve style.yml This command open http://localhost:8080 in your default browser. 22

• http://localhost:8080

Charites view Tile boundaries, etc… Legend 23

Edit your layer Charites serve command watches your changes and reload style when you edit style. layers/landcover-grass.yml id: landcover-grass …. paint: fill-color: '#d8e8c8' fill-opacity: 1 paint: fill-color: '#ff0000’ fill-opacity: 1 24

How to manage layers Use !!inc/file in layers array in style.yml. layers: - !!inc/file layers/background.yml - !!inc/file layers/landcover-glacier.yml - !!inc/file layers/landuse-residential.yml - !!inc/file layers/landuse-commercial.yml … Layers are loaded from top to bottom. 25

Support matrix Charites version Mapbox Support MapLibre version Node type <= v1.x OK v2 v14 commonjs v2.x NG v4 v20 ESM 26

How to add sources You can add sources in sources in style.yml. sources: openmaptiles: type: vector url: https://tile.openstreetmap.jp/data/planet.json takeshima: type: vector url: https://tile.openstreetmap.jp/data/takeshima.json hoppo: type: vector url: https://tile.openstreetmap.jp/data/hoppo.json 27

Using variable You can use variable like $waterColor . In style.yml: $waterColor: 'ff0000' In layers/water.yml: paint: fill-color: '$waterColor' 28

Output your JSON file Run following command: charites build style.yml style.json You can upload your style in github pages, static website or your tileserver gl instance. 29

Introduce of other tools to compile JSON format for MapLibre GL. 30

Pkl https://pkl-lang.org/ Pkl is simple language to generate JSON, YAML, Property List, and other format. Also, Visual Studio Code supports Pkl via extension. 31

• https://pkl-lang.org/

Pkl example (1) style.pkl version = 8 name = "Bright" center = new Listing {0 0} zoom = 0 sources = import("sources.pkl") sprite = import("sprite.pkl").sprite glyphs = import("glyphs.pkl").glyphs layers = import("layers.pkl").layers sources.pkl module sources openmaptiles { type = "vector" url = "https://tile.openstreetmap.jp/data /planet.json" } 32

Pkl example (2) style.pkl version = 8 name = "Bright" center = new Listing {0 0} zoom = 0 sources = import("sources.pkl") sprite = import("sprite.pkl").sprite glyphs = import("glyphs.pkl").glyphs layers = import("layers.pkl").layers layers.pkl module layers layers = new Listing { import("layers/background.pkl") import("layers/landcover-glacier.pkl") import("layers/landuse-residential.pkl") import("layers/landuse-commercial.pkl") import("layers/landuse-industrial.pkl") import("layers/landuse-cemetery.pkl") import("layers/landuse-hospital.pkl") import("layers/landuse-school.pkl") import("layers/landuse-railway.pkl") … } 33

extends layers/extends/aeroway.pkl open module aeroway extends "openmaptiles.pkl" `source-layer` = "aeroway" type = "line" layers/aeroway-taxiway.pkl extends "extends/aeroway.pkl" id = "aeroway-taxiway" minzoom = 4 filter { "all" new { "in" "class" "taxiway" } new { "==" "$type" "LineString" } } layout { `line-cap` = "round" `line-join` = "round" visibility = "visible" } … 34

Variable (1) - background color variable.pkl layers/background.pkl background_color = "#f8f4f0" text_field = "{name:latin} {name:nonlatin}" … text_font_italic { "Noto Sans Italic" } … import "../variables.pkl" as v id = "background" type = "background" paint { `background-color` = v.background_color } 35

Variable (2) - text field and font variable.pkl layers/waterway-name.pkl background_color = "#f8f4f0" text_field = "{name:latin} {name:nonlatin}" … text_font_italic { "Noto Sans Italic" } … import "../variables.pkl" as v layout { … `text-field` = v.text_field `text-font` = v.text_font_italic … } 36

Output JSON format Run following command: pkl eval -f json style.pkl Output style.json: pkl eval -f json style.pkl > style.json 37

Validate your style You can use “gl-style-validate” command. Install: npm install @maplibre/maplibre-gl-style-spec --global For bash: pkl eval -f json style.pkl|gl-style-validate For zsh: gl-style-validate <(pkl eval -f json style.pkl) 38

Full Example - OSM Bright style https://github.com/smellman/openmaptiles-bright-pkl I converted OpenMapTiles’s OSM Bright style to Pkl by hand. 39

• https://github.com/smellman/openmaptiles-bright-pkl
• https://github.com/openmaptiles/osm-bright-gl-style

Language matrix JSON YAML Pkl comment NG OK OK extend NG OK(yaml-include) OK variable NG Limited(Charites) OK preview OK(Maputnik / VS Code) OK(Charites) Manually readable 🤔 😊 😊 writable 🤔 😊 🤔 40

Summary I recommend to use Maputnik for beginner. If you are professional, Charites(YAML) or Pkl are useful to edit your own style with your text editor. 41

Resources Charites: https://github.com/unvt/charites YAML: https://yaml.org/spec/1.2.2/ Pkl: https://pkl-lang.org/main/current/language-reference/index.h tml Thank you! 42

• https://github.com/unvt/charites
• https://yaml.org/spec/1.2.2/
• https://pkl-lang.org/main/current/language-reference/index.html