Atlaslog
Atlaslog / Field Notes / Tiles
Field note · Tiles

512-pixel tiles laid out as 256: blurry basemap and shifted features

Quick answer

After switching to 512x512 tiles the basemap looks softer and vectors are shifted by roughly half a tile, worsening toward the map edge. `tileSize` stayed at 256, so Leaflet compressed each tile and halved its coverage.

Last verified 2026-11-03 · Multiple versions · Cite this page
Applies to: Leaflet 1.9.x / OpenLayers 9.x / mapbox raster tiles
Symptom
Checklist
  1. Check the intrinsic size of a tile in the network panel
  2. Read the width style on `.leaflet-tile` in the DOM
  3. Measure the offset at a tile boundary; half a tile width indicates the mismatch
  4. Check whether `detectRetina` is also enabled
  5. Confirm the service's real tile size from its documentation
Fix

Set `tileSize: 512` together with `zoomOffset: -1` and `detectRetina: false`; in OpenLayers pass `tileSize: 512` to the source and `createXYZ({ tileSize: 512, maxZoom: 19 })` to the tile grid.

Code
const img = document.querySelector('.leaflet-tile');
console.log(img.naturalWidth, img.clientWidth);   // 512 256  <- 尺寸不匹配
L.tileLayer('https://tile.example.com/{z}/{x}/{y}.png', {
  tileSize: 512,
  zoomOffset: -1,
  minZoom: 1,
  maxZoom: 19,
  detectRetina: false        // 已经用 512 了,不要再开
}).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). 512-pixel tiles laid out as 256: blurry basemap and shifted features. https://www.jingweizhi.com/en/cookbook/tile-512-retina.html (accessed 2026-11-03).