Implement dynamic font support /font/<name>/<start>-<end> (#755)

This implements dynamic font protobuf generation, allowing users to
request font ranges on the fly, and combining them in any order, e.g.
`Font1,Font2,Font3`, same as with sprites and tiles

This is a first iteration, without any multithreading support. In
theory, this could be done far faster by generating SDFs with multiple
threads.

### Current process
* during init, figure out all glyphs available in each font, and store
them as a bitset
* during request:
* combine requested bitsets to figure out which glyph should come from
which font file
* load those glyphs from files (using a single instance of the freetype
lib)
  * convert them to SDFs and package them into a protobuf

---------

Co-authored-by: Lucas <[email protected]>

Cargo.toml

@@ -17,6 +17,7 @@ actix-rt = "2"
 actix-web = "4"
 anyhow = "1.0"
 async-trait = "0.1"
+bit-set = "0.5.3"
 brotli = "3"
 cargo-husky = { version = "1", features = ["user-hooks"], default-features = false }
 clap = { version = "4", features = ["derive"] }
@@ -35,6 +36,7 @@ log = "0.4"
 martin-mbtiles = { path = "./martin-mbtiles", version = "0.6.0", default-features = false }
 martin-tile-utils = { path = "./martin-tile-utils", version = "0.1.0" }
 num_cpus = "1"
+pbf_font_tools = { version = "2.5.0", features = ["freetype"] }
 pmtiles = { version = "0.3", features = ["mmap-async-tokio", "tilejson"] }
 postgis = "0.9"
 postgres = { version = "0.19", features = ["with-time-0_3", "with-uuid-1", "with-serde_json-1"] }

debian/config.yaml

@@ -29,3 +29,7 @@ worker_processes: 8
 #     - /path/to/mbtiles.mbtiles
 #   sources:
 #     mb-src1: /path/to/mbtiles1.mbtiles
+
+# fonts:
+#   - /path/to/font/file.ttf
+#   - /path/to/font_dir

docs/src/21-run-with-cli.md

@@ -19,6 +19,9 @@ Options:
   -s, --sprite <SPRITE>
           Export a directory with SVG files as a sprite source. Can be specified multiple times
 
+  -f, --font <FONT>
+          Export a font file or a directory with font files as a font source (recursive). Can be specified multiple times
+
   -k, --keep-alive <KEEP_ALIVE>
           Connection keep alive timeout. [DEFAULT: 75]
 
@@ -28,7 +31,7 @@ Options:
   -W, --workers <WORKERS>
           Number of web server workers
 
-  -b, --auto-bounds <BOUNDS>
+  -b, --auto-bounds <AUTO_BOUNDS>
           Specify how bounds should be computed for the spatial PG tables. [DEFAULT: quick]
 
           Possible values:

docs/src/30-config-file.md

@@ -183,4 +183,10 @@ sprites:
   sources:
     # SVG images in this directory will be published as a "my_sprites" sprite source
     my_sprites: /path/to/some_dir
+
+# Font configuration
+fonts:
+  # A list of *.otf, *.ttf, and *.ttc font files and dirs to search recursively.
+  - /path/to/font/file.ttf
+  - /path/to/font_dir
 ```

docs/src/36-sources-sprites.md

@@ -1,6 +1,6 @@
 ## Sprite Sources
 
-Given a directory with SVG images, Martin will generate a sprite -- a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. `icons/bicycle.svg` will be available as `icons/bicycle` sprite image.
+Given a directory with SVG images, Martin will generate a sprite -- a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. `icons/bicycle.svg` will be available as `icons/bicycle` sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation.
 
 ### API
 Martin uses [MapLibre sprites API](https://maplibre.org/maplibre-style-spec/sprite/) specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately.

docs/src/37-sources-fonts.md

@@ -0,0 +1,65 @@
+## Font Sources
+
+Martin can serve glyph ranges from `otf`, `ttf`, and `ttc` fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly.
+The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation.    
+
+## API
+Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces.
+
+When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph.
+
+| Type     | API                                            | Example                                                      |
+|----------|------------------------------------------------|--------------------------------------------------------------|
+| Single   | `/font/{name}/{start}-{end}`                   | `/font/Overpass%20Mono%20Bold/0-255`                         |
+| Combined | `/font/{name1},{name2},{name_n}/{start}-{end}` | `/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255` |
+
+Martin will show all available fonts at the `/catalog` endpoint.
+
+```shell
+curl http://127.0.0.1:3000/catalog
+{
+  "fonts": {
+    "Overpass Mono Bold": {
+      "family": "Overpass Mono",
+      "style": "Bold",
+      "glyphs": 931,
+      "start": 0,
+      "end": 64258
+    },
+    "Overpass Mono Light": {
+      "family": "Overpass Mono",
+      "style": "Light",
+      "glyphs": 931,
+      "start": 0,
+      "end": 64258
+    },
+    "Overpass Mono SemiBold": {
+      "family": "Overpass Mono",
+      "style": "SemiBold",
+      "glyphs": 931,
+      "start": 0,
+      "end": 64258
+    }
+  }
+}
+```
+
+## Using from CLI
+
+A font file or directory can be configured from the [CLI](21-run-with-cli.md) with one or more `--font` parameters.
+
+```shell
+martin --font /path/to/font/file.ttf --font /path/to/font_dir
+```
+
+## Configuring from Config File
+
+A font directory can be configured from the config file with the `fonts` key.
+
+```yaml
+# Fonts configuration
+fonts:
+  # A list of *.otf, *.ttf, and *.ttc font files and dirs to search recursively.
+  - /path/to/font/file.ttf
+  - /path/to/font_dir
+```

docs/src/SUMMARY.md

@@ -14,6 +14,7 @@
   - [MBTiles and PMTiles File Sources](34-sources-files.md)
   - [Composite Sources](35-sources-composite.md)
   - [Sprite Sources](36-sources-sprites.md)
+  - [Font Sources](37-sources-fonts.md)
 - [Usage and Endpoint API](40-using-endpoints.md)
   - [Using with MapLibre](41-using-with-maplibre.md)
   - [Using with Leaflet](42-using-with-leaflet.md)

martin/Cargo.toml

@@ -56,6 +56,7 @@ actix-http.workspace = true
 actix-rt.workspace = true
 actix-web.workspace = true
 async-trait.workspace = true
+bit-set.workspace = true
 brotli.workspace = true
 clap.workspace = true
 deadpool-postgres.workspace = true
@@ -68,6 +69,7 @@ log.workspace = true
 martin-mbtiles.workspace = true
 martin-tile-utils.workspace = true
 num_cpus.workspace = true
+pbf_font_tools.workspace = true
 pmtiles.workspace = true
 postgis.workspace = true
 postgres-protocol.workspace = true