Vektorkaardi juhend

Praktiline juhend näidetega: kaart lehele MapLibre'iga, stiili ja TileJSON-i kasutamine, oma stiili ehitamine ning tile'de avamine QGIS-is.

Autentimine

Stiili-, sprite-, TileJSON- ja tile-päringud nõuavad API-võtit query-parameetriga key; ainult query-stringis (päise või küpsisega võtit edastada ei saa; positsioon query's ei loe). Ainult fondid ja /health on võtmeta. Võtmel peab olema vektorkaardi (tiles) teenuseõigus ja see võib olla seotud päritoluga; siis töötab ta ainult lubatud veebilehelt (brauser saadab Origin/Referer).

...&key=docs_382d376eaaa6d004b7b93b7d

Server kirjutab stiili ja TileJSON-i sees olevad URL-id ümber nii, et sinu võti liigub automaatselt kaasa; piisab, kui annad võtme ühe korra, stiili-URL-is.

Kiirstart: kaart lehele (MapLibre GL JS)

Täielik minimaalne leht: kopeeri, asenda võti ja ava brauseris:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.js"></script>
  <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.css">
  <style> html, body, #map { margin: 0; height: 100%; } </style>
</head>
<body>
  <div id="map"></div>
  <script>
    const map = new maplibregl.Map({
      container: 'map',
      style: 'https://api.elemroot.com/styles/v1/elemroot/style.json?key=docs_382d376eaaa6d004b7b93b7d',
      center: [24.75, 59.44],   // [pikkus, laius]: Tallinn
      zoom: 10
    });
    map.addControl(new maplibregl.NavigationControl());
  </script>
</body>
</html>

Rohkem ei olegi vaja: stiil viitab ise õigetele tile-, sprite- ja fondi-URL-idele. Töötav näide: examples.elemroot.com/vector-map.

Stiil ja sprite'd

Stiil on MapLibre style spec'i (version: 8) dokument nimega Elemroot v1. See ühendab kaks allikat: planet_baltics-v1 (põhikaart) ja globallandcover-v1 (maakatte taust); ning defineerib kihtide kujunduse. Sprite'id sisaldavad kaardimärke ja mustreid.

TileJSON ja oma stiili ehitamine

Kui tahad kujundada kaardi ise, kasuta allikana TileJSON-i. Vastuses on tile-URL-i mall, zoom-vahemik ja kihtide loend koos väljadega (vector_layers):

curl "https://api.elemroot.com/tiles/v1/planet_baltics-v1.json?key=docs_382d376eaaa6d004b7b93b7d"

{
  "tilejson": "3.0.0",
  "name": "OpenMapTiles + OpenMapTiles",
  "scheme": "xyz",
  "minzoom": 0,
  "maxzoom": 14,
  "center": [24.904322, 56.98397, 14],
  "tiles": [
    "https://api.elemroot.com/tiles/v1/planet_baltics-v1/{z}/{x}/{y}.mvt?key=docs_382d376eaaa6d004b7b93b7d"
  ],
  "vector_layers": [ { "id": "aerodrome_label", "fields": { … } }, … ]
}

Oma stiilis viita allikale nii:

"sources": {
  "elemroot_map": {
    "type": "vector",
    "url": "https://api.elemroot.com/tiles/v1/planet_baltics-v1.json?key=SINU_VOTI"
  }
},
"glyphs": "https://api.elemroot.com/fonts/{fontstack}/{range}.pbf"

Tile'de otsekasutus

Üksik tile on gzip-pakitud Mapbox Vector Tile (protobuf), XYZ-skeemis. Tavaliselt pärib neid kaarditeek ise; käsitsi kontrolliks:

curl -s --compressed -o tile.mvt -w "%{http_code} %{content_type}\n" \
  "https://api.elemroot.com/tiles/v1/planet_baltics-v1/10/584/305.mvt?key=docs_382d376eaaa6d004b7b93b7d"

Vastuse sisutüüp on application/x-protobuf ja tile on alati gzip-pakitud (Content-Encoding: gzip, ka ilma Accept-Encoding päiseta); kaarditeegid pakivad ise lahti; käsitsi salvestades kasuta --compressed. Tühja koha (andmeteta) tile vastab 204 No Content: see on normaalne, mitte viga. Ruudustik on Web Mercator (EPSG:3857), tile'i sisemine ulatus 4096; x/y väärtus väljaspool 0…2z−1 ei anna 404, vaid mähitakse ümber (mod 2^z); 404 tuleb ainult tundmatu tileset'i või liiga suure z korral.

Fondid (glyph'id)

Kohanimede kuvamiseks laeb kaarditeek glyph-PBF faile mustriga /fonts/{fontstack}/{range}.pbf (võtmeta, vahemikud sammuga 256):

curl -s -o glyphs.pbf "https://api.elemroot.com/fonts/Noto%20Sans%20Regular/0-255.pbf"

Saadaval on täpselt need fontstack'id: üksikfondid Noto Sans Regular, Noto Sans Bold, Noto Sans Italic, Roboto Regular, Roboto Medium, Roboto Bold, Roboto Italic, Open Sans Regular, Open Sans Semibold, Arial Unicode MS Regular ning eelehitatud varufondiga stack'id Roboto Regular,Noto Sans Regular, Roboto Medium,Noto Sans Regular, Roboto Bold,Noto Sans Bold, Roboto Italic,Noto Sans Italic, Open Sans Regular,Arial Unicode MS Regular.

Tileset'id ja kihid

Mõlema tileset'i TileJSON bounds on kogu maailm: kaardi algvaate jaoks anna center/zoom ise (stiili enda vaikevaade on maailmakaart). Atributsioon: valmis stiil kuvab selle ise; © Elemroot © OpenStreetMap (OpenMapTiles skeem) ja maakattekihil © ESA WorldCover; oma stiili ehitades säilita need viited.

Täpne kihtide ja väljade loend tuleb TileJSON-i vector_layers väljast (vt eespool). Skeemi kirjeldus: openmaptiles.org/schema.

QGIS ja teised töölauakliendid

QGIS (3.14+): Browser → Vector Tiles → New Generic Connection:

Parameetrid

* = kohustuslik; tabelid genereeritakse OpenAPI-YAML-ist. Võti key (query) on kohustuslik kõigil peale fontide ja /health: vt autentimine.

Tile'd: /tiles/v1/{tileset}/{z}/{x}/{y}.mvt

Fondid: /fonts/{fontstack}/{range}.pbf

Millal mida kasutada

Sagedasemad ülesanded ja neile vastav ots. Kõik read on elusalt kontrollitud.

Puhverdamine ja CORS

Stiil, fondid ja tile'd tulevad päisega Access-Control-Allow-Origin: *; kaardi saab panna mis tahes veebilehele. Tile'del ja TileJSON-il lisatakse see päis vastuseks brauseri Origin päisele (Vary: Origin); brauseris on see alati olemas; curl-iga ilma Origin-ita päist ei paista ja see pole viga.

Veakäsitlus

Edasi

Näited galeriis

• Lihtne vektorkaart
• Aluskaartide vahetus: vektor, raster ja ortofoto
• Maailmakaart Equal Earth projektsioonis (EPSG:8857)
• Kaardivaate juhtimine
• Kaamera lend mööda rada
• Kaardisiltide keel
• 3D-hooned
• Markerid ja hüpikaknad
• Oma andmekiht aluskaardil
• Oma 3D-objektid aluskaardil
• Punktide tihedus: soojuskaart ja hexagonid