Atlaslog / Field Notes / Tiles
Field note · Tiles
Tile directories start at level 1, so the map renders one level too large
Quick answer
The offline package exported by MOBAC contains levels 1 through 19 and no level 0, while the client is configured to start at zoom 0. Every request is one level off, so the basemap looks magnified and the top level returns blanks.
Symptom
- The map at zoom control 0 shows the level-1 picture while vectors sit at half the basemap scale
- Requests for `18/x/y.png` fall outside the 19-level directory and return blank images
- `tileload` logs `{ x: 0, y: 0, z: 1 }` although the client believes it is at zoom 0
Checklist
- List the tile root and check whether the smallest directory is `0` or `1`
- Print `e.coords` in the `tileload` event and compare with the requested path
- Compare the largest directory number with the configured `maxZoom`
- Check `minNativeZoom` and `maxNativeZoom`, which change upscaling but not requested levels
- Decide whether to shift the client or renumber the directory
Fix
Align the client with the directory by setting `minZoom: 1, maxZoom: 19`, or keep zoom 0 and add `zoomOffset: 1` so requests use `z + 1`; set `maxNativeZoom: 19` with a higher `maxZoom` to upscale instead of requesting missing levels.
Code
map.on('tileload', e => console.log(e.coords, e.tile.src));
// tiles/1/0/0.png
// tiles/19/...L.tileLayer('/tiles/{z}/{x}/{y}.png', {
minZoom: 1,
maxZoom: 19,
tileSize: 256
}).addTo(map);
L.tileLayer('/tiles/{z}/{x}/{y}.png', {
minZoom: 0,
maxZoom: 18,
zoomOffset: 1, // 请求 z = zoom + 1
tileSize: 256
}).addTo(map);
Watch out
- Raising `maxZoom` to 19 while leaving `minZoom: 0`, which still requests a non-existent level 0
- Confusing `maxNativeZoom` with `maxZoom` and expecting it to shift the request level
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). Tile directories start at level 1, so the map renders one level too large. https://www.jingweizhi.com/en/cookbook/tile-z-offset.html (accessed 2026-11-03).