Design Proposal: Allow overzoom for sparse pyramids tiles

[etienneJr]

Design Proposal: Allow overzoom for sparse pyramid tiles

Motivation: help deploy light pmtiles

Vector tiles are a great opportunity for developers to host their own tile server rather than relying on a third-party service. However a full planet pmtiles in OpenMapTiles schema is more than 70 Go, which is too much for small-scale web hosting.

Hopefully most maps do not require full detail of the whole planet, but the whole planet only up to an intermediate zoom (let's say z10) to get a nice map, then full details (let's say z11-z14) only in an area of interest (a city, a state, a country, ...).

It is possible in pmtiles to store such sparse pyramid tiles, so I was expecting this behavior:

• in the area of interest (right side): display the available z11-z14 tiles
• in the rest of the world (left side): overzoom in the last available level (z10)

But the acual maplibre behavior is this one, with nothing visible in the rest of the world

This behavior is perfectly normal once you have noticed that the tile server logically responds an empty tile, so maplibre logically displays a transparent tile.

This behaviour is perfect when 2 sources have been declared : you want the user to see the 2nd source below when the 1st one is not available. But it is not suited for 1 sparse pmtiles source for which the "show me what's below" behavior would be to display the last available level.

MapLibre is able to overzoom the last available level when it is the maxzoom level and also when the tile server responds with a 404 error instead of an empty tile (this is the way I used to prepare the 1st image above)

Proposed Change

I propose to allow the user to choose the expected behavior when the tile server responds an empty tile:

• the default behavior would be the actual one: display nothing (for people with multiple sources)
• a new available behavior would be to overzoom in the last available level (for people with 1 source), as is the case today when the tile server responds an error

This could be implemented in maplibre-style-spec during source definition, for example with a new parameter overzoomEmptyTile: true/false or emptyTileHandling: 'overzoom'/'transparent' that allows the user to choose the desired behavior

sources: {
  'openmaptiles': {
     type: 'vector',
     url: `pmtiles://${PMTILES_URL}`,
     overzoomEmptyTile: true,
  }
}

API Modifications

I don't know what to write in this section.

Migration Plan and Compatibility

I don't expect any compatibility issues, as the default behaviour would still be to display a transparent tile.

Rejected Alternatives

Several people (in this discussion on pmtiles repo and this one on maplibre GL JS repo) proposed to prepare 2 separate files and declare these as 2 sources. This solution is not suitable because:

1. 2 sources make 2 calls whereas only 1 is used
2. to apply the same style to both file sources, you have to duplicate the entire style definition. And for styles with a lot of layers (based on OpenMapTiles schema for example), it makes a lot of duplicated content.
3. more problematic, since the z10 tile is overzoomed everywhere, you get in the area of interest a strange superposition of both sources:

This proposal will allow a single-file solution that can be easily deployed by people with few map-coding skills, on small-scale servers.

[prusswan]

I recognize this as an issue of variable effective maxzoom in a single tileset, which is something not accounted for by the vector tile specs (if a tileset declares maxzoom=n it should have the tiles at that level - whether the tile server respond with an error or blank tile should not matter). While I don't expect libraries to handle this, if a solution can be found for maplibre JS, then it can possibly be applied for other client libraries as well. In cases where you are using/combining external tile sources that you cannot modify, client side fixes would be necessary anyway.

[xabbu42]

I finally got around to test all combinations of maplibre-native/maplibre-gl-js, raster/vector tiles and 204/404 http result for this. As suspected, maplibre-native has overzoomEmptyTiles: true per default for raster sources both for 204 and 404 results, but not for vector sources. maplibre-gl-js on the other hand only has overzoomEmptyTiles: true for raster sources and 404 results.

First step should be to get a definitive conclusion what the correct default behavior is and fix the discrepancy between maplibre-native and maplibre-gl-js.

Side node, while I understand overzoomEmptyTiles from the context, it reads strange as it is not the empty tile itself that gets overzoomed.

[HarelM]

Can you put it in a table? I don't want to interpret the sentence wrong...
I agree the behavior should be consistent across web and native.

[xabbu42]

sure

For vector sources:

Server response	204	404
maplibre-gl-js	empty	empty
maplibre-native	empty	empty

For raster sources:

Server response	204	404
maplibre-gl-js	empty	overscale
maplibre-native	overscale	overscale

empty: rendering an empty tile, i.e. a vector tile without any geometry or a transparent image
overscale: falling back to a tile with a lower zoom level and scaling it to the higher zoom level

[xabbu42]

actually I'm not sure I really tested the vector 404 case, will have to redo that. it seems strange to me that there is no fallback in that case...

[etienneJr]

I agree, in my case (vector tiles, maplibre-GL-JS, 404 error) I observed overscale behavior.

[xabbu42]

Just checked the 404 vector tiles case again with maplibre-gl-js 4.7.1 and maplibre-native glfw-app on mac. I don't see any overscaling at all. So the tables seem to be correct as written.

[etienneJr]

The behaviour you've observed seems really strange to me, I've deployed a sparse pyramid pmtiles on my website for 1 month, with pmtiles protocol throwing 404 errors (using new option errorOnMissingTile: true, see here), and overscaling is working perfectly well on maplibre-gl-js.
You can see here the border between the 2 areas:
https://playguide.eu/app/playground/1738f899-d174-4be0-9987-03231b60645a

• south display z14 tiles
• north display overscaled z12 tiles
• console display 404 errors

Do we use different versions of maplibre-gl-js?

[xabbu42]

I don't see any 404 errors in console or the network tab on your example. As far as I understand pmtiles uses range queries so thats a different case than the ones I tested. It is relevant though that the behavior for missing tiles is different when using pmtiles and range queries than with a full GET requests per tile.

[etienneJr]

Don't you see these errors in the console ? At least after scrolling the map ?

Maybe my understanding is wrong and they are not exactly "404" errors, but for sure they are errors thrown here by pmtiles.js and caught by maplibre-gl-js, which triggers overscaling.

With the default option errorOnMissingTile: false, pmtiles.js returns a blank array, and maplibre-gl-js display an empty tile.

[xabbu42]

I see those errors and they are not 404 errors so there is no conflict between our observations, just two different data points. Good to know that the default for pmtiles is the same as in my case and you enabled the difference with an option.

Can you test what the default is with a sparse raster pmtile by any chance to cover all cases?