Atlaslog
Atlaslog / Field Notes / Loading & display
Field note · Loading & display

WMTS TileMatrix starts at 0, so every tile is one level off

Quick answer

GeoServer names its WMTS levels EPSG:4326:0 through EPSG:4326:21, but level 0 is 1:559082264 and covers the globe with a 2x1 grid, not the single tile that XYZ expects. The client is therefore always one zoom level out.

Last verified 2026-11-03 · Multiple versions · Cite this page
Applies to: GeoServer 2.23 WMTS 1.0.0 · OpenLayers 9.x · Leaflet 1.9.x
Symptom
Checklist
  1. Open GetCapabilities and read each TileMatrix Identifier together with its ScaleDenominator.
  2. Compute the level-0 resolution as ScaleDenominator * 0.00028 m/px and compare it with the lon/lat grid.
  3. Map the frontend z values against the Capabilities identifiers and look for a constant one-level offset.
  4. Request TILEMATRIX=EPSG:4326:0 manually and check whether it returns a 2x1 grid at 0.703125 degrees per pixel.
  5. Inspect the tileGrid: OpenLayers createXYZ() assumes one tile at z=0.
Fix

Align the client grid with Capabilities: copy the resolutions array into an explicit WMTSTileGrid, or change GeoServer's TileMatrixSet start level to 1 so it matches the XYZ convention.

Code
<TileMatrix>
  <ows:Identifier>EPSG:4326:0</ows:Identifier>
  <ScaleDenominator>279541132.0143589</ScaleDenominator>
  <TopLeftCorner>90 -180</TopLeftCorner>
  <TileWidth>256</TileWidth>
  <TileHeight>256</TileHeight>
  <MatrixWidth>2</MatrixWidth>
  <MatrixHeight>1</MatrixHeight>
</TileMatrix>
const matrixIds = [];
for (let z = 0; z <= 21; z++) matrixIds[z] = 'EPSG:4326:' + z;

L.tileLayer('http://localhost:8080/geoserver/gwc/service/wmts?SERVICE=WMTS&REQUEST=GetTile' +
  '&VERSION=1.0.0&LAYER=gis:districts&STYLE=&FORMAT=image/png' +
  '&TILEMATRIXSET=EPSG:4326&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}', {
  tileSize: 256,
  tms: false,
  maxZoom: 21,
  minZoom: 0,
  zoomOffset: 0
}).addTo(map);
Watch out
All 120 field notesChinese originalRunnable examples
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Cite this page

Atlaslog (2026). WMTS TileMatrix starts at 0, so every tile is one level off. https://www.jingweizhi.com/en/cookbook/wmts-tilematrix-offset.html (accessed 2026-11-03).