Support MapBox

[shesio]

Please add support for MapBox maps in MapComposeMP. Thank you!

[p-lr]

Yes, I'm aware that would be nice.

[jershell]

I'm taking this issue. If anyone else is working on it too, please let me know so we can coordinate and avoid duplicate work.

[brezinajn]

I've made some initial progress in Mapbox integration. I have rough but almost complete impl. If you want to compare notes/colab, I'm all for it. Currently I don't have capacity to do a proper PR until mid summer.

[jershell]

I have rough but almost complete impl

Did you implement the full specification?
The most difficult trouble it`s expressions and filters

https://maplibre.org/maplibre-style-spec/expressions/
https://maplibre.org/maplibre-style-spec/layers/#filter

https://github.com/mapbox/tilejson-spec/blob/master/2.2.0/README.md

[jershell]

🚧 Problem Overview

I've encountered a structural mismatch between how tile zooming is handled in MapCompose versus MapLibre. We should decide how we want to handle this going forward.

📽 "Stupid" rasterization from MVT to PNG (my current status)

▶️ Watch the video

---

❌ Why treating vector tiles as if they were raster is problematic

When vector tiles are processed as if they were already rasterized (e.g., simply fetched and painted onto the screen like static images), this goes against the core principles of vector rendering and introduces several serious issues:

1. Excessive number of tile requests
2. Loss of vector rendering benefits (scalability, crispness on high-DPI screens)
3. Incorrect scaling of symbols and text
4. Layer filtering logic becomes ineffective
5. Client-side performance degradation (due to increased draw calls and memory usage)
6. Broken interactivity and hit-testing (you can’t query vector features anymore)

---

✅ Correct approach

• Only one tile should be rendered at the lowest zoom level
• All logic related to scaling, filtering, and styling should be handled on the client side
• The client should decide which features to render, how to scale text and lines, and how to apply style rules dynamically

---

🎯 Key point

MapCompose does not stretch a single tile to fill the entire screen. Instead, it always divides the world into a fixed fullSize × fullSize pixel grid and tries to cover the viewport using as many tiles as necessary.

If the viewport is larger than the rendered world at a certain zoom level, it starts wrapping or requesting “extra” tiles to fill the space.

---

Let's we treat MapLibre as the reference standard

MapCompose (raster) and MapLibre (vector) interpret the world at minimum zoom very differently:

• In MapLibre, zoom level 0 always renders a single tile (0/0/0) that covers the entire world.
• In MapCompose, as many tiles are rendered as needed to fill the viewport, even at the lowest zoom.

To match MapLibre's behavior precisely, we either need to:

• Patch MapCompose, or
• Apply a workaround in the tile provider (e.g., always returning only tile 0/0/0 at zoom 0).

---

What MapLibre does

1. At zoom = 0, the logical world is covered by 1 tile of 256×256 pixels
   This is based on the Web Mercator projection (EPSG:3857), where the world is projected into a fixed number of tiles.

   • At zoom = 0: 1 tile (256×256) covers the entire world
   • At zoom = 1: 2×2 tiles
   • And so on: tile matrix = 2^zoom × 2^zoom

👉 This tile matrix model is a foundational concept used in OpenMapTiles, Mapbox, MapLibre, Google Maps, and similar systems.

---

What MapCompose currently does

MapCompose calculates tile layout based on scale and fullSize, not based on the standardized tile matrix.

As a result, there’s no fixed tile matrix for a given zoom level. For example, at the lowest zoom level (level = 0), it may load 4, 6, or 9 tiles depending on the viewport size — which violates the MVT (Mapbox Vector Tile) specification.

---

🔧 What needs to be changed in MapCompose

1. Fix scaleForLevel to follow the tile matrix model:

Current:

scaleForLevel[level] = 1.0 / 2.0.pow((levelCount - level - 1))

Should be:

scaleForLevel[level] = 1.0 / 2.0.pow(level)

This change makes level == zoom, instead of level = maxZoom - zoom.

---

2. Update getLevel(scale) logic:

Current:

val partialLevel = levelCount - 1 - magnifyingFactor + ln(scale) / ln(2.0)

Should be:

val partialLevel = log2(1.0 / scale)
return partialLevel.roundToInt().coerceIn(0, levelCount - 1)

---

3. Bind fullSize to the tile matrix size:

Instead of using a fixed pixel size (e.g., 16384 x 16384), use:

fullSize = tileSize * 2^maxZoom

This ensures the world is correctly scaled across all zoom levels. If fullSize is inconsistent (e.g., 18000 pixels), the matrix alignment breaks.

---

4. Add support for world-wrapping

MapLibre wraps the world horizontally, allowing infinite panning.

MapCompose does not. To replicate expected behavior:

• Enable horizontal wrap-around, or
• Lock scroll boundaries to the world bounds.

---

(https://docs.mapbox.com/help/glossary/zoom-level/) or [EPSG:3857](https://epsg.io/3857)

[p-lr]

I have to point out that MapCompose can be configured to be used using standard WMTS tile source. In the OSM demo, you can see that the map size is computed like so:

fun mapSizeAtLevel(wmtsLevel: Int, tileSize: Int): Int {
    return tileSize * 2.0.pow(wmtsLevel).toInt()
}

In this case, there is a perfect match between the level in the library and the level you're talking about (let's call it the wmts level). It's just that MapCompose can represent other maps which aren't necessarily world maps. I have an app which uses MapCompose to display small maps (of some forests, islands, etc). Once you know the extent of the captured area, you can make the correspondance with the wmts level if needed. It really is an implementation detail of the TileStreamProvider.

As for your 4th point, you're absolutely right. MapCompose isn't designed for infinite scrolling. That could be something to work on.

But if we have a feature complete renderer which bascically does the pbf -> png conversion, that would be huge already.

[jershell]

complete renderer which bascically does the pbf -> png conversion

Great! I’ll focus solely on rasterization (PBF → PNG) for now. Once the MR is ready, we can continue with integrating the raster output into MapCompose.

[p-lr]

This is the real challenge indeed. With this additional step, we can finally have a complete Kotlin library to display vector tiles.

[DestBro]

This is the real challenge indeed. With this additional step, we can finally have a complete Kotlin library to display vector tiles.

Is this done ? Any samples on how to use vector tiles map with MapCompose ?

[jershell]

This is the real challenge indeed. With this additional step, we can finally have a complete Kotlin library to display vector tiles.

Is this done ? Any samples on how to use vector tiles map with MapCompose ?

In this branch (https://github.com/p-lr/MapComposeMP/tree/feature/mvt-support) we are working on MVT tile support, and in this PR (#29) you can find screenshots of the current progress in the description.

Is this done ? Any samples on how to use vector tiles map with MapCompose ?

No. @jershell didn't give any update for quite a while now. He either stopped working on it or forked the project :/

Regarding further progress, we’ve run into some difficulties with the 3D layer. It’s necessary to implement rendering of 3D objects at the engine level and use the current rendering result as a texture. This part raises the most questions, and I haven’t started exploring it yet. The previous work I did during my vacation, but once it ended, work life started “attacking” me and kept me extremely busy. Sadly, I’m not sure when I’ll be able to continue my research.