improve docs for raster source parameter: tileSize

[ttomasz]

Not setting this parameter can have significant effect on how the map is displayed when using e.g. OpenStreetMap's tiles.

I am attaching two files with examples (apparently github doesn't allow attaching html files so they are suffixed with txt).

It seems that with the raster source serving 256px tiles:

• if the "tileSize" is not set:
  • library will download tiles at the same zoom level as the map, resulting map is blurry
• if the "tileSize" is set to 256:
  • library will download tiles at zoom level + 1 and scale them appropriately, resulting map looks nice

It would be nice if this was documented so people avoid making blurry maps by accident. maplibre_test.html.txt maplibre_test2.html.txt

[wipfli]

Intersting, thanks. Ideally you share a stackblitz or jsbin or codesandbox or so. Then others can just click on the link and see the problem dirctly in their browser. But thanks still for the htmls!

I wonder if we have an example on the docs website with osm tiles?

[ttomasz]

Yeah, I actually initially made stackblitz snippets as I thought the issue was with me rewriting my app to react but forgot about them :sweat_smile: https://stackblitz.com/edit/js-cactms?file=index.html

[ttomasz]

There is one example of adding XYZ tiles with different tile provider (and style) https://maplibre.org/maplibre-gl-js-docs/example/map-tiles/

[wipfli]

Ah that sort of hand-painted map from Stamen looks really nice :)

This example uses osm tiles: https://maplibre.org/maplibre-gl-js-docs/example/3d-extrusion-floorplan/

[xabbu42]

From my understanding, the blurry maps are the result of maplibre-gl-js assuming the default tile size of 512px and then getting 256px tiles instead. I suppose we could log an error in this case (i.e. getting tiles with the wrong size from a raster source)?

Also I do not understand the current description of the tileSize parameter https://maplibre.org/maplibre-gl-js-docs/style-spec/sources#raster-tileSize at all (I'm not a native speaker). So I definitely agree that this documentation should be improved.

[dnomadb]

I'd love to take a stab at this as I think tileSize is one of GL-JS's more underrated features. I've used it multiple times to:

• optimize for heavy dynamic tiling (use a larger tile size to request less tiles at the trade-off of resolution)
• use "mega tiles" (1024x1024) in certain applications where fewer, larger requests are advantageous
• support retina resolution when only 256x256 tiles are available (by using a tileSize of 128)

I actually had this page kicking around to show how it can work: https://dnomadb.github.io/tile-size/?tileSize=2048&resampling=nearest

[HarelM]

Should I move this issue to the docs repo?

[dnomadb]

Should I move this issue to the docs repo?

@HarelM Since the documentation for this aspect of the style spec is contained here: https://github.com/maplibre/maplibre-gl-js/blob/608c0fa3e6050072786ded848353ff3be3dd8579/src/style-spec/reference/v8.json#L254, I think it makes sense to leave it in this repo.

That said, I think that a simplified example of how this is used (potentially similar to the above) would add a lot of clarity, so I could open a new issue there if people are 👍 .

[HarelM]

I don't think a new issue is needed. Feel free to submit a PR.