2021-07-15-unvt-exercise-day05

Material for a casual vector tile exercise (Day 05). Exercise of making style.json using hocon-parser.

Transcript

1. UNVT Exercise Day 5 15 July 2021 By Taro Ubukawa (Senior Geospatial Expert at UN Geospatial Information Section)
2. Whole schedule So far, about vector tile (VT), we have practiced the followings: • VT consumption in GIS tools like QGIS. • Simple VT tile styling. • VT hosting as static file. • VT data conversion. • Simple conversion • Advanced conversion with nodejs • Vector tile hosting Today’s content: • Styling using hocon One of the good points of vector tile map is to be able to make various style maps from a single source. Let’s learn efficient way of styling.
3. Today’s contents - Data hosting (advanced) • Today’s Goal: We will be able to make style.json using HOCON-parser. Let’s try making various maps with different styles from the same source. Produce Host Style Optimize Import UNVT workflow of developing vector tile for base map Supported by UNVT, open source scripts Source DB Web APP Users Our focus today.
4. (Review of previous workshop/exercise) Styling - A format of styling information How can we add style information to the vector tile map? mapbox-gl.js take map styles that conform to the Mapbox Style Specification. For detail, go to: https://docs.mapbox.com/mapbox-gl-js/style-spec/ (Other map libraries also follows main part of that specification.) • A “style.json” • is a JSON object • with specific root level and nested properties • How we can make it? • By manual writing using text editor (it is tough work though…) • Mapbox Studio • Maputnik (an open source visual editor for mapbox style spec.) • UN Vector Tile Toolkit (e.g. naru with HOCON) Today, we will use unvt/nanban.
5. Here are the main properties at the root level • version: Style specification number. Must be 8. (required) • source: Data source. (required) • glyphs: A URL for glyphs (text font, etc). (optional) • sprite: A base URL for the sprite image (map symbols). (optional) • layers: Layers drawn in the order of this array. (required) • center: Default map center (optional) • zoom: default zoom level (optional) Source and layers are important parts. From https://docs.mapbox.com/mapbox-gl-js/style-spec/root/ (Review of previous workshop/exercise) Styling - Main components of a style.json
6. Let’s start the exercise!
7. (0)Preparation: copy exercise data • Copy data from the MS Teams channel. Or download it at https://github.com/unvt/ezPrac (ex5-data) * mbtiles is not included in GitHub repository • Start command prompt (I used Windows Powershell), and move to the working directory. Zipped file here
8. (0) Preparation: Start Vector Tile hosting If the vector tile is already uploaded to the web, you can just skip this process. Here, we will establish a local server to host the vector tile. (Refer to the day 4.) Please copy clearmap-test.mbtiles from MS Teams channel in mbtiles directory if you clone the repository from GitHub. At the working directory, run: > Docker run -it --rm -v ${PWD}:/data -p 8836:8836 unvt/nanban > cd /data > npm install > npm install sqlite3 > node app.js Keep running during the practice. (You can stop it by ctrl+c) We will use port 8836 to establish a local server. Please use another port if you already use it.
9. (0) Preparation: Local server is running.. • At http://localhost:8836/index.html , you will see that the server is running. (You can see the sample map, but cannot see the Plain and Dar map now.)
10. (1) Start docker again for style editing • Open another CLI. Go to the working directory, and start docker. > docker run -it --rm -v ${PWD}:/data unvt/nanban > cd /data • Try “rake” to obtain a new style.json in htdocs directory. > rake By running rake, we are making style.json from files in hocon folder (hocon/style.conf, etc.). Tips: You do not have to specify the port this time.
11. (1) Please check: Can you see the sample map? • http://localhost:8836/sample-map.html style: http://localhost:8836/style.json
12. FYI: About HOCON • HOCON: Human-Optimized Config Object Notation They are config files to make a JSON file in easy way!! Procedure: 1. Make/edit config files 2. Run parse-hocon to make a style.json
13. (2) Editing the file - “style.conf” • This is a kind of the primary file for the style editing. It includes information on “version,” and several components (_root, sources, layers, metadata) which are described in the different files. Now you do not have to change them. Please just confirm. Let’s see what is in the hocon folder
14. (2) Editing the file - “_root.conf” • You can specify several elements in the style.json. • “sprite” is the location of the map symbol, etc. • “glyphs” is the location of the text fonts. Use # to make some comments Now you do not have to change them. But you can try changing the center and/or zoom if you want. Let’s see what is in the hocon folder
15. (2) Editing the file - “sources.conf” • You can specify the source. • You can freely name the source name (we are using “v” now). • You can add more than one source. Now you do not have to change them. But you can try changing max/min of the zoom level if you want. Let’s see what is in the hocon folder
16. (2) Editing the file - “layers.conf” • This is a list of layers. • You can add layers, but please make sure that you prepare config files for these layers. • For example, you may find there are “background.conf,” “pg-landmass.conf,” and so forth. • Practice: Please try to delete # in the line 10, 11, 12 to add some symbols. Let’s see what is in the hocon folder
17. (2) Editing the file - information of each layer • From easy one to complicated one. • You will be familiar with them once you practice. Practice: For example… • Change the color of the ocean and/or landmass • Change the width of the coastline • Change the minimum zoom of the ocean label (pt-lab-water-ocean.conf) Etc… Let’s see what is in the hocon folder
18. (3) Run parse-hocon to make style.json • Once you are ready, run the following command again. You will get new style.json > rake Check the map to see if there is any change! • http://localhost:8836/sample-map.html style: http://localhost:8836/style.json
19. (Review) For Efficient styling – UNVT experience Use of hocon parser Each component and its sub-components can be written separately as a text file. Then, merged using hocon parser.
20. (4) Make various styles • Run “rake plain” and “rake dark” to obtain “clearmap-plain.json” and “clearmap-dark.json”. They are developed from the files in “hocon-plain” and “hocon-dark” respectively. Check Rakefile to see the script.
21. (4) Make various styles - images http://localhost:8836/dark.html http://localhost:8836/plain.html
22. (5) For further application - We can have more layers for larger map We can immediately get the style.json (Several thousands lines)
23. Layer structure is important • When you design the style, it is important to properly understand the layer structure of the data source(s). • Layer names, their max/min zoom, attribution, etc.
24. Summary • You now understood how you can make a style.json with HOCON.
25. Review of the whole exercises Produce Host Style Optimize Import UNVT workflow of developing vector tile for base map Supported by UNVT, open source scripts Source DB Web APP Users • Thank you for your interest and participation. • I hope you understood some detail about the vector tile in these exercises. • Any feedback will be appreciated.
26. References • Install Docker Desktop on Windows: https://docs.docker.com/docker-for-windows/install/ • UNVT onyx: https://github.com/un-vector-tile-toolkit/onyx • UNVT naru: https://github.com/unvt/naru • @mapbox/mbtiles: https://www.npmjs.com/package/@mapbox/mbtiles • mapbox style specification: https://docs.mapbox.com/mapbox-gl-js/style-spec/ • Fujimura, H. (2021): UNVT Workshop: Introduction and Application https://speakerdeck.com/hfu/unvt-workshop-introduction-and-application
27. More practice? • https://github.com/unvt/ezPrac