Skip to content

Add OpenMapTiles vector map#4042

Merged
tomhughes merged 1 commit into
openstreetmap:masterfrom
maptiler:omt-vector-map
Jul 22, 2025
Merged

Add OpenMapTiles vector map#4042
tomhughes merged 1 commit into
openstreetmap:masterfrom
maptiler:omt-vector-map

Conversation

@zdila

@zdila zdila commented May 23, 2023

Copy link
Copy Markdown
Contributor

This pull request adds OpenMapTiles vector tiles among the featured layers. To ensure compatibility with the current stack based on Leaflet, it uses maplibre-gl-leaflet binding.
The main advantage for users is support for labels in multiple languages: users can easily switch by changing language preferences in settings.

196365626-243c978f-256c-4a53-a6a7-aee2d63f6c74

An official email with a link to this PR was sent, together with an edit of the “Featured tile layers” wiki page.

@tomhughes

Copy link
Copy Markdown
Member

I thought we had agreed that adding support for vector tile layers should be separate from adding any specific layer - certainly at the least I'd like them to be separate commits.

The API key should probably be in the configuration file as well, as with the thunderforest layers, rather than hardcoded.

What are all the 3D terrain bits about?

@zdila

zdila commented May 23, 2023

Copy link
Copy Markdown
Contributor Author

I thought we had agreed that adding support for vector tile layers should be separate from adding any specific layer - certainly at the least I'd like them to be separate commits.

Support for vector tiles is actually just adding maplibre-gl and @maplibre/maplibre-gl-leaflet to package.json.

If you agree, I can prepare such PR.

The API key should probably be in the configuration file as well, as with the thunderforest layers, rather than hardcoded.

I'll look at it.

What are all the 3D terrain bits about?

It is a link to a demo site that shows full capability of vector maps (map rotation, animation, 3D terrain) which is not possible with Leaflet and maplibre-gl-leaflet library.

@tomhughes

tomhughes commented May 23, 2023

Copy link
Copy Markdown
Member

So are you actually adding two layers here then? The main vector tiles layer and the 3D one? Only the 3D one doesn't seem to be global so I don't think it's going to pass OWG review.

I can't look at the other one because it's not actually working currently.

@zdila

zdila commented May 23, 2023

Copy link
Copy Markdown
Contributor Author

This PR adds only one layer - vector map with carto-like style. Most of the code is actually about updating the link URL in the attribution of this map so that it would point to the same view of the external 3D map demo.

@zdila

zdila commented May 23, 2023

Copy link
Copy Markdown
Contributor Author

You can see it live at http://osm.openmaptiles.org/

@tomhughes

Copy link
Copy Markdown
Member

Ah yes it does work over HTTP but all the other links were HTTPS which doesn't work.

I think the 3D stuff should be separated out - most of the code is only actually there to do that I think and I think that's going to be a lot more contentious that the rest of it.

@zdila

zdila commented May 23, 2023

Copy link
Copy Markdown
Contributor Author

Do I understand correctly that the issue we are talking about is the "3D map ⛰️." link in the footer?

We added it there to allow visitors to see the OSM in 3D. We would love to have it directly on osm.org. However, it is not technically possible because the site runs on Leaflet. Therefore, we added it at least as an external link.

@tomhughes

Copy link
Copy Markdown
Member

Yes that's what I'm talking about - it wouldn't be acceptable as a layer on the site anyway as it doesn't appear to cover the whole world and I think that also makes linking to it questionable which is why I'd rather separate that decision/discussion from the question of adding the vector tile layer to the site.

@zdila

zdila commented May 23, 2023

Copy link
Copy Markdown
Contributor Author

Can you please report an area that is missing terrain/map? Because I am checking it on my side and the coverage is global - even in the remote places.

@tomhughes

tomhughes commented May 23, 2023

Copy link
Copy Markdown
Member

Maybe I just don't understand how to operate it then... I clicked the bottom button to switch back to 2D mode, panned to my home area, then tried to switch back to 3D mode by pressing the same button again and nothing happened.

Specifically I was looking at https://labs.maptiler.com/showcase/osm-3d-terrain/#style=openstreetmap&lang=en&mode=3d&position=15.46/51.76264/-0.00868 which is 2D and I can't find any way to switch to 3D there?

@tomhughes

Copy link
Copy Markdown
Member

Oh if I hold on that button and move my mouse I can make it tilt and pan...

@zdila

zdila commented May 23, 2023

Copy link
Copy Markdown
Contributor Author

You can also drag the map with the right mouse button, or with Ctrl key pressed. Anyway, that area is not very hilly.

@gravitystorm

Copy link
Copy Markdown
Collaborator

Great to see progress on this, thank you for the PR.

The main advantage for users is support for labels in multiple languages: users can easily switch by changing language preferences in settings.

This is great! Do you have any guidance for us as to how it handles regional languages, e.g. pt-PT vs pt-BR? Or sr vs sr-Latn? And what happens if you pick a language that is not supported by GL-based renderings, like my (Burmese)?

I want to make sure that the translations work for all of the languages that our user interface works in, hopefully so that there's no mismatch between what you can pick in the UI and what then happens with this layer.

I also noticed on the wiki that it says "map labels translations from Wikidata" - can you clarify this? How does this interact with the translated labels available in OSM? If a contributor spots a mistake on the map, can they edit OSM to fix it, or do they have to edit something on Wikidata?

We added it there to allow visitors to see the OSM in 3D. We would love to have it directly on osm.org. However, it is not technically possible because the site runs on Leaflet. Therefore, we added it at least as an external link.

I don't think the layer attribution is the right place for linking to external sites to view other renderings.

If we want to link to external sites to view other renderings, which haven't been through the new layer approval process, then let's discuss this separately. And if we want to adapt the site to support alternative (i.e. non-leaflet) tech, then let's discuss that separately too. But I don't think such links should be part of the attribution for another layer, and I definitely don't think that should be part of this PR.

@zdila

zdila commented May 25, 2023

Copy link
Copy Markdown
Contributor Author

This is great! Do you have any guidance for us as to how it handles regional languages, e.g. pt-PT vs pt-BR? Or sr vs sr-Latn? And what happens if you pick a language that is not supported by GL-based renderings, like my (Burmese)?

Supported languages of OMT are documented at https://docs.maptiler.com/schema/planet/#languages

Comparison
OSM OMT Language
af Afrikaans
aln Gheg Albanian
am Amharic
ar ar Arabic
arz Egyptian Arabic
ast Asturian
az az Azerbaijani
ba Bashkir
be-Tarask Belarusian (Taraškievica)
be be Belarusian
bg bg Bulgarian
bn Bengali
br br Breton
bs bs Bosnian
ca ca Catalan
ce co Chechen, Corsican
cs cs Czech
cy cy Welsh
da da Danish
de de German
diq Zazaki
dsb Lower Sorbian
el el Greek
en-GB English (UK)
en en English
eo eo Esperanto
es es Spanish
et et Estonian
eu eu Basque
fa Persian
fi fi Finnish
fit Tornedalen Finnish
fr fr French
fur Friulian
fy fy West Frisian
ga ga Irish
gcf Guadeloupean Creole French
gd gd Scottish Gaelic
gl Galician
gsw Swiss German
he he Hebrew
hi hi Hindi
hr hr Croatian
hsb Upper Sorbian
hu hu Hungarian
hy Armenian
ia Interlingua
id id Indonesian
is is Icelandic
it it Italian
ja ja Japanese
ja-Hira Japanese (Hiragana)
ja-Latn Japanese (Latin)
ja_rm Japanese (Romanization)
ja_kana Japanese (Kana)
ka ka Georgian
kab Kabyle
kk-cyrl kk Kazakh (Cyrillic)
km Khmer
kn kn Kannada
ko ko Korean
ko-Latn Korean (Latin)
ksh Colognian
ku-Latn Kurdish (Latin)
ku Kurdish
la Latin
lb lb Luxembourgish
lt lt Lithuanian
lv lv Latvian
mk mk Macedonian
ml Malayalam
mo Moldovan
mr Marathi
ms Malay
mt Maltese
my Burmese
nb Norwegian Bokmål
nds Low German
ne Nepali
nl nl Dutch
nn Norwegian Nynorsk
no Norwegian
nqo N’Ko
oc oc Occitan
pa Punjabi
pl pl Polish
pnb Western Punjabi
ps Pashto
pt-BR Portuguese (Brazil)
pt-PT Portuguese (Portugal)
pt pt Portuguese
rm Romansh
ro ro Romanian
ru ru Russian
sat Santali
sc Sardinian
scn Sicilian
sco Scots
sk sk Slovak
skr-arab Saraiki (Arabic)
sl sl Slovenian
sq sq Albanian
sr-Latn sr-Latn Serbian (Latin)
sr sr Serbian
sv sv Swedish
ta ta Tamil
te te Telugu
th th Thai
tl Tagalog
tr tr Turkish
tt Tatar
uk uk Ukrainian
vi Vietnamese
xmf Mingrelian
yi Yiddish
yo Yoruba
zh Chinese
zh-CN Chinese (China)
zh-HK Chinese (Hong Kong)
zh-TW Chinese (Taiwan)

Currently if the language is not supported then local language is used - same as on Carto map - value from the name key of the tag.

I want to make sure that the translations work for all of the languages that our user interface works in, hopefully so that there's no mismatch between what you can pick in the UI and what then happens with this layer.

I will discuss it with my team. In any case current implementation doesn't fallback to the other languages in the list but I will implement it into this PR. Also falling back to main locale if sub-locale is not available (pt-BR -> pt).

I also noticed on the wiki that it says "map labels translations from Wikidata" - can you clarify this? How does this interact with the translated labels available in OSM? If a contributor spots a mistake on the map, can they edit OSM to fix it, or do they have to edit something on Wikidata?

We have decided to use names primarily from wikidata because there are more translations than in OSM. If the name is not in wikidata then one from OSM is used.

We added it there to allow visitors to see the OSM in 3D. We would love to have it directly on osm.org. However, it is not technically possible because the site runs on Leaflet. Therefore, we added it at least as an external link.

I don't think the layer attribution is the right place for linking to external sites to view other renderings.

If we want to link to external sites to view other renderings, which haven't been through the new layer approval process, then let's discuss this separately. And if we want to adapt the site to support alternative (i.e. non-leaflet) tech, then let's discuss that separately too. But I don't think such links should be part of the attribution for another layer, and I definitely don't think that should be part of this PR.

We will adjust it in this PR.

@pnorman

pnorman commented May 26, 2023

Copy link
Copy Markdown
Contributor

Currently if the language is not supported then local language is used - same as on Carto map - value from the name key of the tag.

What about when the language of the name tag is in a script Maplibre does not support?

@zdila

zdila commented May 26, 2023

Copy link
Copy Markdown
Contributor Author

What about when the language of the name tag is in a script Maplibre does not support?

Not sure if I understand you correctly, but for unsupported languages their local name will be displayed.

If you meant something else then please give me some example. You can try switching to (unsupported) language by setting it as primary in your browser (until I add a fallback to other languages your browser accepts - then try just with a single language configured).

@zdila

zdila commented May 26, 2023

Copy link
Copy Markdown
Contributor Author

Meanwhile I have removed 3D map link in the attribution.

@zdila

zdila commented May 26, 2023

Copy link
Copy Markdown
Contributor Author

The API key should probably be in the configuration file as well, as with the thunderforest layers, rather than hardcoded

done

@jachym

jachym commented May 26, 2023

Copy link
Copy Markdown

Maybe I just don't understand how to operate it then... I clicked the bottom button to switch back to 2D mode, panned to my home area, then tried to switch back to 3D mode by pressing the same button again and nothing happened.

Specifically I was looking at https://labs.maptiler.com/showcase/osm-3d-terrain/#style=openstreetmap&lang=en&mode=3d&position=15.46/51.76264/-0.00868 which is 2D and I can't find any way to switch to 3D there?

@tomhughes The map is 3D, but London is rather flat, sending better position:
https://labs.maptiler.com/showcase/osm-3d-terrain/#style=openstreetmap&lang=en&mode=3d&position=12.51/55.4648/-3.3975/-4.80/85.00

As metioned, you hold Ctrl key and can change the view angle.

@pnorman

pnorman commented May 27, 2023

Copy link
Copy Markdown
Contributor

Not sure if I understand you correctly, but for unsupported languages their local name will be displayed.

Maplibre doesn't support some scripts (e.g. Burmese, Lao, and other Brahmic scripts), so it can't display the local name.

@ZeLonewolf

ZeLonewolf commented May 27, 2023

Copy link
Copy Markdown

Maplibre doesn't support some scripts (e.g. Burmese, Lao, and other Brahmic scripts), so it can't display the local name.

That's not exactly accurate. The issue is that MapLibre doesn't support ligatures and combining characters correctly, and instead displays them anywhere from slightly to terribly wrongly. However, OSM-Carto also renders some of these scripts wrongly as the examples below will show (and should probably be documented if they're not already). Whether the "wrong" rendering makes the label unreadable or just slightly off will depend heavily on the script involved, and in my experience, it's the worst in Right-to-Left scripts.

This is what MapLibre displays for the United States label, in Lao:

image

However, it is supposed to look like this:
image

The issue is that the squiggly line above the second-to-last character is supposed to be directly over it, not off to one side. This issue is pervasive across all ligature/combiner scripts. While a Lao reader might still understand the script above, it would definitely look wrong, and this problem in other scripts results in mangled text that's absolutely unreadable to native speakers.

This is something which has always been broken in mapbox-gl and is a high priority for maplibre-gl to get right, and it's documented in maplibre/maplibre#193.

Examples of rendering the Lao capital of Vientiane, which should appear in local script as:

ວຽງຈັນ

Google Maps:
image

OSM Americana (based on MapLibre):
image

OSM Carto:
image

However, looking at these examples, it seems that osm-carto isn't actually any different from what MapLibre is producing. Both MapLibre and osm-carto have the same issue with the diacritic being shifted to the right slightly.

Let's take a look at Kathmandu, Nepal, which is supposed to appear as:

काठमाडौँ

Google Maps:
image

OSM Americana
image

OSM Carto:
image

Mandalay, Burma, perhaps?

Should be:

မန္တလေး

Google Maps:
image

OSM Americana:
image

OSM Carto:
image

Burmese is where we really start to see the problem, with that infinity-sign looking diacritic that's supposed to be under the second character coming in rather mangled. However, OSM-Carto also gets it slightly wrong by jamming the ligature up into the character when there's supposed to be space between them.

@LaoshuBaby

LaoshuBaby commented Jun 3, 2023

Copy link
Copy Markdown
Contributor

图片

It seems that this new vector map does not handle the display of Chinese very well. It displays the Traditional and Simplified varient at the same time, because a DWG member with an Asian cultural background combined the two varients in name:zh, and usually The user will choose zh-CN or zh-TW two locales (for example, my browser uses zh-CN, so you can see other UI translations are displayed in my locale), but the label text is not correct from zh-CN match to name:zh-Hans.


图片

Even if I forcibly specify locale=zh-TW, the name:zh value mixed with various variants will still be preferred as the display label text

@SomeoneElseOSM

Copy link
Copy Markdown

Re "... because a DWG member ... combined the two variants in name:zh" that sounds like a tagging issue that's best discussed elsewhere - perhaps somewhere at https://community.openstreetmap.org/ ?

@LaoshuBaby

LaoshuBaby commented Jun 4, 2023

Copy link
Copy Markdown
Contributor

Re "... because a DWG member ... combined the two variants in name:zh" that sounds like a tagging issue

Yes, use variants combined value is a tagging issue, we can discuss in other places. Whether this kind of edit is reasonable will not be discussed on this github issue @SomeoneElseOSM

My reply is about vector map's label text(name:zh) can't match browser's locale settings(zh-CN/zh-TW), There should be a fallback from name:zh-Hans/t->name:zh, I don’t know how the new vector map handles the ICU problem, is about technical.

Comment thread app/assets/javascripts/leaflet.map.js Outdated
Comment thread app/assets/javascripts/leaflet.map.js Outdated
@tomhughes

Copy link
Copy Markdown
Member

To be clear what languages are used in OSM tags are not directly relevant here - this is a mapping from web site locales to locales used by this layer.

How the layer maps from OSM tags to it's supported languages is a matter for the layer and the tools used to generate it's tiles from the OSM data.

@1ec5

1ec5 commented Jun 4, 2023

Copy link
Copy Markdown
Collaborator

Understood, but those OpenMapTiles properties are directly tied to the deprecated OSM keys, so it would essentially be a way to enable OSM users to enter nonstandard codes in OSM preferences to see those tags’ value. (As far as I can tell, your language preference can include language codes that the website has no localization for.)

I guess it’s fine if these nonstandard codes end up being an obscure, undocumented edge case, but if they do get used, then that would be problematic for other components that rely on this same preference for localization, such as iD.

@Triomphe346

Copy link
Copy Markdown

How the layer maps from OSM tags to it's supported languages is a matter for the layer and the tools used to generate it's tiles from the OSM data.

I see on their own demo that they could correctly handle different Chinese variants (attach sample is Simplified Chinese only demo with 'zh-CN' browser setting).

Demo of MapTiler in Simplified Chinese

It seems that they do not explicitly document this. If it is possible to support zh-Hans/zh-Hant variants disregarding the listed supported language code? (may need mapping zh-CN browser setting to zh-Hans in MapTiler & zh-HK/zh-TW browser setting to zh-Hant in MapTiler manually) @tomhughes

Comment thread app/assets/javascripts/leaflet.map.js Outdated

@hlfan hlfan left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn’t see anything particularly noteworthy in your changes compared to 4da9615, the few comments I’ve left are about things you haven't touched yet.

Comment thread app/assets/javascripts/leaflet.map.js Outdated
Comment thread package.json Outdated
Comment thread app/assets/javascripts/leaflet.map.js Outdated
Comment thread app/assets/javascripts/leaflet.map.js
@petr-hajek
petr-hajek force-pushed the omt-vector-map branch 3 times, most recently from f8bd0b0 to fdc3e9d Compare July 1, 2025 21:13
Comment thread vendor/assets/leaflet/leaflet.osm.vector.js Outdated
Comment thread config/layers.yml
@pnorman

pnorman commented Jul 2, 2025

Copy link
Copy Markdown
Contributor

I think there was a question that still needed answering from MapTiler about the featured layer discussions. I'll have to review emails or check notes to be sure

@tomhughes

Copy link
Copy Markdown
Member

I think the only thing is that somebody suggested (and I can't remember where I saw it) that the layer included additional buildings that weren't from OSM data but I haven't had a chance to investigate that claim yet.

@petr-hajek

Copy link
Copy Markdown

In the end I keep maplibre v4 with maplibre-gl-leaflet 0.0.22 since for some reason the custom attribution got broken after updating. Someone else can update this in some followup PR.

@hlfan hlfan left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whether or not the style.json path definition changes, this now looks good to me. That could also be worth revisiting when there's more than one vector style.
Tests pass in my fork hlfan#18.
If you wanna do other reviewers a favor, go through the code comments and mark applicable ones as resolved.

@petr-hajek

Copy link
Copy Markdown

Whether or not the style.json path definition changes, this now looks good to me. That could also be worth revisiting when there's more than one vector style. Tests pass in my fork hlfan#18. If you wanna do other reviewers a favor, go through the code comments and mark applicable ones as resolved.

I'm sorry, unfortunately I cannot resolve them, I suppose since this is not originally my PR, so if you can resolve those raised by you, it'd be great, thanks.

@jachym

jachym commented Jul 3, 2025

Copy link
Copy Markdown

I think the only thing is that somebody suggested (and I can't remember where I saw it) that the layer included additional buildings that weren't from OSM data but I haven't had a chance to investigate that claim yet.

This style is using OSM data only - adjusted according with the request of the community.

@tomhughes

Copy link
Copy Markdown
Member

Is there an api key I can use for testing? You can let me have it privately if you prefer...

@petr-hajek

Copy link
Copy Markdown

Is there an api key I can use for testing? You can let me have it privately if you prefer...

I believe it should work with the Free account so just by signing up here you can get one: https://cloud.maptiler.com/account/keys/

@tomhughes

Copy link
Copy Markdown
Member

Thanks @petr-hajek I had in fact already registered a key there I had just forgotten about it ;-)

I think this is good to merge now - what do you want to do about a key for us to use in production? Am I OK just to register a key for that or do you need to do something special?

@hlfan

This comment was marked as resolved.

@tomhughes

Copy link
Copy Markdown
Member

Yes I deliberately didn't ask for that here as there's no point having two people do the same work - it's just a conflict I can resolve when merging. Indeed I've just done a test this afternoon of merging them both and resolving the conflicts.

@petr-hajek

Copy link
Copy Markdown

Thanks @petr-hajek I had in fact already registered a key there I had just forgotten about it ;-)

I think this is good to merge now - what do you want to do about a key for us to use in production? Am I OK just to register a key for that or do you need to do something special?

I'll double check with my teammates here in MapTiler and reach out to you in PM.

@petr-hajek

Copy link
Copy Markdown

@tomhughes PM sent from https://www.openstreetmap.org/user/bananaboy on OSM - in case you want to use a different means of communication, please let me know there

@tomhughes

Copy link
Copy Markdown
Member

Thanks for all the work on this, which I think is good to merge now.

@tomhughes
tomhughes merged commit d61d265 into openstreetmap:master Jul 22, 2025
16 checks passed
@Firefishy

Copy link
Copy Markdown
Member

Some initial PR: https://en.osm.town/@osm_tech/114902624740876388

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.