Rasterkaardi juhend

Praktiline juhend näidetega: rastertile'd Leaflet'i ja MapLibre'iga, ortofoto kihivahetus, WMTS-ühendus QGIS-is ning EPSG:3301 kihid OpenLayers'iga.

Autentimine

Iga päring vajab key-parameetrit ja võtmel peab olema raster-teenus. Ilma võtmeta või vale võtmega vastab teenus 403 (keha {"error":"invalid_api_key"}). Võti võib olla seotud päritoluga: siis töötab ta ainult lubatud veebilehelt (brauser saadab Origin/Referer). Näidetes kasutatav docs_… võti on kiiruspiiranguga demo-võti (liiga tihedad päringud → 429); oma rakenduse jaoks küsi personaalne võti.

curl -s -o tile.png \
  'https://pump.elemroot.com/xyz/eestig/12/2329/1202.png?key=docs_382d376eaaa6d004b7b93b7d'

Kihid ja ruudustikud

Kumba ruudustikku valida? Veebirakenduses kasuta EPSG:3857 kihte (eestig, eestio3857); need on standardses veebi-merkaatori ruudustikus, mida Leaflet ja MapLibre mõistavad ilma lisateekideta. EPSG:3301 kihid on Eesti riiklikus L-EST97 ruudustikus: neid vajad GIS-tarkvaras (WMTS kaudu) või kui su rakendus töötab L-EST97 koordinaatides; veebis nõuavad nad OpenLayers'it + proj4-t või Leafletit + Proj4Leafletit (vt allpool).

Kiirstart: Leaflet

Lihtsaim viis rasterkaart lehele saada (töötav täisnäide: Leaflet + EPSG:3301):

<div id="map" style="height: 400px"></div>
<script>
  const map = L.map('map').setView([59.437, 24.7536], 12); // Tallinn

  L.tileLayer('https://pump.elemroot.com/xyz/eestig/{z}/{x}/{y}.png?key=docs_382d376eaaa6d004b7b93b7d', {
    maxZoom: 18,
    attribution: '© Elemroot'
  }).addTo(map);
</script>

Ortofoto jaoks vaheta kiht: eestio3857/{z}/{x}/{y}.jpeg (atributsioon © Maa-amet).

MapLibre GL JS

MapLibre's on rastertile'd raster-tüüpi allikas. See sobib hästi ka siis, kui tahad ortofotot kuvada vektorkaardi kõrval või all:

const map = new maplibregl.Map({
  container: 'map',
  style: {
    version: 8,
    sources: {
      orto: {
        type: 'raster', tileSize: 256, maxzoom: 18,
        tiles: ['https://pump.elemroot.com/xyz/eestio3857/{z}/{x}/{y}.jpeg?key=docs_382d376eaaa6d004b7b93b7d'],
        attribution: '© Maa-amet'
      }
    },
    layers: [{ id: 'orto', type: 'raster', source: 'orto' }]
  },
  center: [24.7536, 59.4370],
  zoom: 12
});

Elus demo kihivahetusega (kaart ↔ ortofoto): näidete galerii „Rasterkaart kihivalikuga”.

WMTS ja QGIS

WMTS on iseennast kirjeldav standard: capabilities-dokument loetleb kihid, ruudustikud ja tile-URL-id. Anna GIS-tarkvarale capabilities-URL koos võtmega: võti kantakse tile-URL-idesse automaatselt edasi:

https://pump.elemroot.com/wmts/1.0.0/WMTSCapabilities.xml?key=docs_382d376eaaa6d004b7b93b7d

QGIS-is:

1. Layer → Add Layer → Add WMS/WMTS Layer → New
2. URL-i lahtrisse pane ülalolev capabilities-aadress (oma võtmega)
3. Connect: vali kiht (nt eesti ruudustikuga est3301 või eestig ruudustikuga webmerc) → Add

EPSG:3301 kihid tulevad QGIS-is õigesse projektsiooni ilma ümberprojekteerimiseta; L-EST97 töövoo jaoks eelista neid.

WMTS REST tile-URL on /wmts/{kiht}/{grid}/{z}/{x}/{y}.{laiend} (TileMatrix/TileCol/TileRow; TileMatrix ID on capabilities'es nullitäidisega 00…20, aga ka paljas 6 sobib). Erinevalt XYZ-otsast on siin laiend kohustuslik ja peab vastama kihi formaadile: kaardikihtidel .png, ortofotol (eestio, eestio3857) .jpeg. Vale laiend, vale grid, tundmatu kiht või ruudustikust väljas tile annavad 400 OGC ExceptionReport-XML-i (InvalidParameterValue / TileOutOfRange). Liides on REST-only (KVP GetTile puudub); capabilities kannab võtme tile-mallidesse edasi.

EPSG:3301 kihid veebis (OpenLayers)

eesti ja eestio elavad Eesti riiklikus ruudustikus: bbox [-211000, 5732000, 1325000, 7268000], algresolutsioon 6000 m/px, iga zoom poolitab. XYZ-teljestik (rea 0 on põhjas). OpenLayers + proj4 näide (töötav täisnäide: OpenLayers + EPSG:3301; sama ruudustik Leafletiga: Leaflet + Proj4Leaflet):

proj4.defs('EPSG:3301',
  '+proj=lcc +lat_1=59.33333333333334 +lat_2=58 +lat_0=57.51755393055556 ' +
  '+lon_0=24 +x_0=500000 +y_0=6375000 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs');
ol.proj.proj4.register(proj4);

const extent = [-211000, 5732000, 1325000, 7268000];
const resolutions = [];
for (let z = 0; z <= 18; z++) resolutions[z] = 6000 / Math.pow(2, z);

const map = new ol.Map({
  target: 'map',
  layers: [new ol.layer.Tile({
    source: new ol.source.XYZ({
      url: 'https://pump.elemroot.com/xyz/eesti/{z}/{x}/{y}.png?key=docs_382d376eaaa6d004b7b93b7d',
      projection: 'EPSG:3301',
      tileGrid: new ol.tilegrid.TileGrid({
        extent, resolutions, tileSize: 256,
        origin: [extent[0], extent[3]]   // NW-nurk = XYZ-teljestik
      }),
      attributions: '© Elemroot'
    })
  })],
  view: new ol.View({
    projection: 'EPSG:3301',
    center: [542000, 6589000],           // Tallinn L-EST97-s
    resolution: 6000 / Math.pow(2, 12)
  })
});

Parameetrid

* = kohustuslik; tabelid genereeritakse OpenAPI-YAML-ist.

XYZ: /xyz/{kiht}/{z}/{x}/{y}.png

WMTS REST: /wmts/{kiht}/{grid}/{z}/{x}/{y}.{laiend}

Millal mida kasutada

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

Veakäsitlus

Formaadid ja viited

• XYZ-otsal on faililaiend URL-is valikuline ja seda ei kontrollita: õige formaat tuleb alati kihist (kaardikihid PNG, ortofotod JPEG); .png, .jpeg, .jpg või laiendita annavad sama tile'i. WMTS-otsal on laiend kohustuslik ja peab klappima kihi formaadiga (vt WMTS).
• Puhverdamine: tile'd ja capabilities tulevad päistega Cache-Control: max-age=604800 (7 päeva), ETag ja Last-Modified; klient tohib neid 7 päeva cache'ida.
• Atributsioon: Elemrooti kihtidel © Elemroot, Maa-ameti kihtidel © Maa-amet.
• Tile'de suurus on 256×256 px.
• Kõik vastused tulevad päisega Access-Control-Allow-Origin: *; sobivad ka CORS-i nõudvatele klientidele (nt MapLibre'i raster-allikas).
• Vektorkaarti (teravam, stiilitav, väiksem maht) vaata Vektorkaardi teenusest; raster sobib siis, kui vajad ortofotot, L-EST97 ruudustikku või kliendipoolt ilma WebGL-ita.

Näited galeriis

• L-EST97 rasterkaart OpenLayersiga
• L-EST97 rasterkaart Leafletiga
• Aluskaartide vahetus: vektor, raster ja ortofoto
• Aadressiotsing Elemrooti rasterkaardil
• Aadressiotsing L-EST97 rasterkaardil
• Oma andmekiht L-EST97 rasterkaardil