feat: enable PMTiles protocol support

[savely-krasovsky]

This patch enables PMTiles protocol for MapLibre-GL. Protocol allows to fetch tiles from a single file. This drastically simplifies the process to self-host own tiles.

Description

I don't like that Immich fetches tiles from cloud. After some research I found Protomaps.com project. Basically they build and allow to download entire map as a single file (123 GiB, https://maps.protomaps.com/builds/) and by using HTTP Range browser can read tiles one-by-one instead of downloading entire file. This format allows to self-host tiles very easily. Basically I just downloaded pmtiles and official Immich styles in JSON and replaced this:

[...]
"sources": {
  "vector": {
    "type": "vector",
    "url": "https://tiles.immich.cloud/v1.json"
  }
},
[...]

By this:

[...]
"sources": {
  "vector": {
    "type": "vector",
    "url": "pmtiles://https://immich.example.org/pmtiles/20250303.pmtiles"
  }
},
[...]

After applying my patch Immich started to understand PMTiles protocol.

How Has This Been Tested?

• Changed map style JSON and tested it with my self-hosted pmtiles file.

Screenrecoring with demo

2025-03-06.025550.mp4

Checklist:

• I have performed a self-review of my own code
• I have made corresponding changes to the documentation if applicable
• I have no unrelated changes in the PR.
• I have confirmed that any new dependencies are strictly necessary.
• I have written tests for new code (if applicable)
• I have followed naming conventions/patterns in the surrounding code
• All code in src/services uses repositories implementations for database calls, filesystem operations, etc.
• All code in src/repositories/ is pretty basic/simple and does not have any immich specific logic (that belongs in src/services)

[savely-krasovsky]

I guess I can write about this something in docs, though I don't want to spend time on it if this PR will receive hard no.

[jrasm91]

Nice!

[savely-krasovsky]

@jrasm91 I force pushed to update author (committed under work credentials previously accidentally) and fixed linter issue. Please approve again!

[savely-krasovsky]

Also want to add that Immich already had transient pmtiles dependency. So if we didn't tree-shake it, current Immich version already include pmtiles reader, though doesn't use it now.

[bo0tzz]

Is this patch really necessary? I would expect it to automatically pick up any supported protocol from the style.json

[savely-krasovsky]

@bo0tzz yes. I also thought that, but it throws error by trying to download file using pmtiles:// scheme and not understanding it. I also tried to just leave link without pmtiles:// prefix but in that case browser literally tries to download entire file.

[zackpollard]

Yea, you have to do it like this. Being able to self host the map tiles has been something on my list of things to offer for a while. We want to build in a solution that just lets you click self host and it will download the pmtiles file to the server and manage that part for you too. We would need this bit anyway so happy for this to go in now and the rest come later.

[zackpollard]

The only thing to be aware of is our styles json isn't built for the latest pmtiles file right now, so there could be some weirdness as it's a newer version than we currently use on the tile server itself.

[savely-krasovsky]

Unfortunately maplibre_gl flutter package still relies on pretty old maplibre-native libs which lack PMTiles support. I prepared a patch for flutter package here: maplibre/flutter-maplibre-gl#552

I tested that patch with Immich app and it works.