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.
Symptom
- A tile's `naturalWidth` is 512 while its DOM `clientWidth` is 256
- Roads and vector points are offset by about 200 px, growing away from the center
- The same zoom level looks blurrier than the previous 256-pixel service
Checklist
- Check the intrinsic size of a tile in the network panel
- Read the width style on `.leaflet-tile` in the DOM
- Measure the offset at a tile boundary; half a tile width indicates the mismatch
- Check whether `detectRetina` is also enabled
- 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
- Keeping `tileSize: 256` for 512-pixel tiles, which downscales the image and halves its coverage
- Combining `detectRetina: true` with 512 tiles and `zoomOffset: -1`, where the two compensations cancel and levels skip
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
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).