Font management for 3D Labels #2661
Description
Context
Migration from Itowns 2D Canvas labels to 3D Labels (see parent issue)
3D Text libraries such as troika-three-text cannot use CSS fonts, they require font files in either :
- OTF format
- TTF format
- WOFF format (Troika uses an internal converter to transform WOFF to OTF)
Description
The objective of this issue is to discuss how fonts could be managed for iTowns labels.
Potential Solutions
I identified a couple ways that different fonts could be used
Google Gstatic API
Troika's official example uses this method, it consists on requesting google's static api to get the fonts as a .woff, this requires a repository containing every supported fonts :
export const FONTS = {
'Roboto': 'https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu4mxM.woff',
'Alex Brush': 'https://fonts.gstatic.com/s/alexbrush/v8/SZc83FzrJKuqFbwMKk6EhUXz6w.woff',
...
}However, some fonts such as Arial are not available on google's api, requiring fallback fonts
Note
Hosting a server with all supported fonts, or allowing user to use their own font files or url could allow to bypass those that are not available on gstatic
Google CSS Fonts API
This method uses google's CSS api to fetch the font via name and characteristics rather than id, removing the need for a repository of supported fonts.
Requesting https://fonts.googleapis.com/css2?family=Roboto returns :
/* cyrillic-ext */
@font-face {
font-family: 'Roboto';
font-style: normal;
font-weight: 400;
font-stretch: 100%;
src: url(https://fonts.gstatic.com/s/roboto/v50/KFOMCnqEu92Fr1ME7kSn66aGLdTylUAMQXC89YmC2DPNWubEbVmZiArmlw.woff2) format('woff2');
unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
}
/* cyrillic */
@font-face {
font-family: 'Roboto';
font-style: normal;
font-weight: 400;
font-stretch: 100%;
src: url(https://fonts.gstatic.com/s/roboto/v50/KFOMCnqEu92Fr1ME7kSn66aGLdTylUAMQXC89YmC2DPNWubEbVmQiArmlw.woff2) format('woff2');
unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
}
It is then possible to extract the gstatic url for the chosen font.
Caution
As of 18-12-2025, Troika does NOT support the current WOFF2 format, requiring a third-party converter
Extract System Font
According to Mozilla's documentation, it may be possible to extract the local fonts to use them with Troika without fetching to google api
Caution
As of 18-12-2025, this feature is experimental and not widely supported
Mapbox CSS Glyph
Mapbox provides a library that can generate SDF glyphs from a CSS font.
The issue is that Troika generates its own glyphs automatically, so that would mean either replacing them or preventing them from being generated at all. I'm not sure if this method can be implemented properly.
According to this issue, it may be possible for simple labels.
Overview
| Method | + | - |
|---|---|---|
| Gstatic | Static font urls unlikely to change | Requires custom list of supported fonts and not every CSS font is available from Google |
| Google CSS Fonts API | Fetching by name, automatic resolving of a wide range of fonts without custom list | Requires third-party WOFF2 decompression (as of 18-12-2025), API could be subject to changes and not every CSS font is available from Google |
| Extract System Font | Every font that the user can render should be available by default | Experimental and not widely supported (as of 18-12-2025) |
| Mapbox CSS Glyph | Availability of CSS fonts without fetching | Could break some Troika features / Make Troika's glyph generation redundant, requires additional copyrights |
It may be possible to combine different methods as well such as using the CSS Fonts API with a Gstatic repository as fallback and allowing user to give a custom font url as well with either local or hosted font.