World · Mercator · 8²
3/2/3Coarse land GeoJSON in Web Mercator. Drawn grid caps at 32²; the red cover tracks the true tile — at high z a shrinking pin with a callout arrow.
Zoom levels · MapLibre math
Zoom is a pyramid, not a stretch.
A vertical dial, a wireframe pyramid, and live numbers for the choices MapLibre actually
makes: tileSize, vector extent, zoom offsets, and overzoom.
3/2/3 Tile pyramid
wireframeEach step multiplies tile count by four. Tap a slab to jump. Overzoom past a source maxzoom reuses the top slab, scaled.
Specimen
3/2/3
Parent 2/1/1 · child index 2 of 4
MapLibre knobs
Same z, different contracts.
Switch the format MapLibre is speaking. Raster cares about tileSize (default 512). Vector cares about local extent (usually 4096). A zoom offset shifts which file URL is requested.
Mode
tileSize
zoomOffset
Equator · one XYZ square at z3. Independent of tileSize / extent.
circumference / (2^z · tileSize). With tileSize 256, one screen
sample covers this at the equator.
MapLibre’s world is 512-based. A 256px source biases canonical tile zoom by log₂(512/256) = 1, then zoomOffset 0.
23 × 23 squares cover the Mercator world.
map.addSource('xyz', {
type: 'raster',
tiles: ['https://example/{z}/{x}/{y}.png'],
tileSize: 256, // MapLibre default is 512
maxzoom: 19
});
// camera z3 → request ~z4 (bias 1, offset 0)Raster datasets
Where native pixels sit in the pyramid.
A COG or imagery layer has a ground sample distance. Below that zoom, many native pixels collapse into one tile pixel. Above it, you are inventing detail (or overzooming).
Native GSD
Display tileSize
Sentinel-2 ~10 m GSD
Match zoom ~z13.9
At current z3 ~1957 native px / tile px
Scale ladder
Where z usually sits.
Current selection
Region · z3
countries · tile 3/2/3
- Tile width (equator)
- 5.01 Mm
- Meters / display pixel
- 20 km
- World tiles
- 64
- Sentinel-2 native fit
- ~1957× / px
At z3, about 1957 Sentinel-2 samples (10 m GSD) land in one display tile pixel. Native match ≈ z13.9.
MapLibre source contract
What the engine requests
Camera zoom is not always the file zoom. Bias, offsets, and maxzoom decide the URL.
- Mode
- raster
- tileSize
- 256px
- 512-world bias
- +1
- zoomOffset
- 0
- Requested source z
- z4
Rendering knobs
How MapLibre paints tiles
These levers change what you see after a tile is fetched — without changing the geographic camera math above.
- Overzoom Past source
maxzoom, MapLibre keeps the top tile and scales it. Vectors stay sharp; rasters soften. - Underzoom / parent reuse If a child tile is missing, a parent can fill in. Coarser data is stretched to the camera zoom.
- tileSize vs 512 world MapLibre’s internal world assumes 512. A 256 raster source shifts canonical tile zoom by +1 so ground resolution stays correct.
- zoomOffset Shifts which
{z}is requested — useful when a pyramid is published one level off from the camera scale you want. - devicePixelRatio On retina displays MapLibre may request denser tiles or scale glyphs/lines so hairlines stay crisp without changing geographic zoom.
- Layer paint Opacity, resample (
linear/nearest), hillshade exaggeration, and symbol collision all happen after decode — they don’t change the tile address. - renderWorldCopies When on, the mercator world repeats horizontally so pans across ±180° stay continuous.
Tip: for a 10 m classification raster, set source maxzoom near z14 and let MapLibre overzoom past that instead
of inventing extra pyramid levels.