Skip to content

Server-side raster tile rendering

Martin can render a style into raster images server-side: as XYZ tiles, or as a single static image at a chosen camera.

Warning

Rendering is not part of the default build. It relies on MapLibre Native, which needs EGL and OpenGL ES at runtime. It renders on the GPU when an EGL driver for it is installed, and on the CPU with Mesa's llvmpipe otherwise. We only ship it where we control the runtime environment. You get it by either:

  • using the -full Docker image variant, tagged :latest-full, or the matching -full Linux-gnu release tarball, or
  • building from source with the rendering feature enabled (Linux only): cargo install martin --features rendering.

The default Docker image, the default release binaries, and cargo install martin do not include rendering.

Limitations of our current implementation:

To enable rendering, you need a build that includes it (see above) and to turn it on in the configuration file:

styles:
    rendering: true

Renders run on a dedicated thread pool. rendering: true sizes it from the logical CPU count, clamped to 2..=8. The long form sets the number of render threads explicitly, how many renderers each keeps, the tile size, the pixel ratios tiles and static images are served at, and the size of the ambient cache:

styles:
    rendering:
        enabled: true
        workers: 4
        # Renderers each tile worker keeps loaded, one per style and pixel ratio [default: 8]
        renderers_per_worker: 8
        # Renderers each static worker keeps loaded, one per style and pixel ratio [default: 2]
        static_renderers_per_worker: 2
        # Width and height of XYZ tiles in pixels: 256 or 512 [default: 512]
        tile_size: 512
        # Whole-number @{n}x pixel ratios served, each 1 to 4 [default: [1, 2]]
        pixel_ratios: [1, 2]
        # MB of MapLibre Native's cache of fetched tiles, glyphs and sprites, 0 to disable [default: 50 MiB]
        ambient_cache_size_mb: 0
        # Indexed PNG palette; `false` keeps full-color RGBA [default: max_colors 128]
        png_palette:
            max_colors: 128
        # Quality per format: WebP 1 to 100 or `lossless`, JPEG 1 to 100 [default: 80 each]
        quality:
            webp: 80
            jpeg: 80

Indexed (palette) PNG

Rendered PNG tiles and static images are indexed (palette) PNGs. For map tiles they are about a quarter of the size of full-color RGBA, with no visible difference. JPEG and WebP are not affected, they follow the quality setting.

Each image gets the smallest palette that stays close to the full-color render, up to max_colors (2 to 256, default 128). Encoding a tile this way takes a few milliseconds of CPU.

styles:
    rendering:
        enabled: true
        png_palette:
            max_colors: 64

Set png_palette: false for full-color RGBA PNGs, for example for imagery or styles with smooth gradients:

styles:
    rendering:
        enabled: true
        png_palette: false

Quality

Rendered WebP and JPEG tiles and static images are lossy at quality 80. Each format has its own quality, as the two degrade differently at the same number. Both are optional, and any value outside the ones below fails at startup. PNG is not affected, see indexed PNG.

  • webp is 1 to 100, or lossless. Lossy WebP is encoded with libwebp. At quality 80, map tiles are about a sixth of the size of lossless WebP, with no visible difference. The alpha channel stays lossless.
  • jpeg is 1 to 100. JPEG has no lossless mode.
styles:
    rendering:
        enabled: true
        quality:
            webp: 90
            jpeg: 90

Lossless WebP keeps every pixel, for example for imagery or styles with smooth gradients:

styles:
    rendering:
        enabled: true
        quality:
            webp: lossless

Rendered XYZ tiles

Martin supports generating a rasterized image for an XYZ tile of a given style.

After enabling rendering, you can use the /style/<style_id>/{z}/{x}/{y}.{filetype} API to get a <style_id>'s rendered png/jpeg/webp content.

Tile size

Tiles are 512×512 px by default, the size MapLibre uses. Set tile_size: 256 to serve 256×256 px tiles, the size most other raster clients (such as Leaflet or OpenLayers) expect by default. Any other value fails at startup.

Pixel ratio

For high-density (retina) screens, add @{n}x after the row to draw the same tile at n times the pixels: /style/<style_id>/{z}/{x}/{y}@2x.png is twice tile_size wide and high (1024×1024 px with the default 512), @3x three times. n must be listed in pixel_ratios ([1, 2] unless configured, each 1 to 4): an unlisted ratio such as @3x is answered with 400 Bad Request, and a malformed suffix such as @0x or @1.5x with 404 Not Found. A tile without a suffix counts as @1x, so pixel_ratios: [2] also refuses it. Every listed ratio needs renderers of its own, so list only the ratios your clients ask for.

In Leaflet, this is the {r}-placeholder (/style/<style_id>/{z}/{x}/{y}{r}.png), which means that on a retina screen, you get the crisp map your users expect.

Renderers per worker

Martin renders XYZ tiles and static images in two separate pools, each with workers threads. Each tile worker keeps a renderer for every style and pixel ratio it has been asked for, up to renderers_per_worker (8 unless configured). Beyond that, the least recently used one is dropped, and loaded again the next time it is needed. Each static worker keeps up to static_renderers_per_worker renderers (2 unless configured), also one per style and pixel ratio. When all of them are in use, Martin loads the new style into the least recently used one, and rebuilds that renderer first if its pixel ratio differs. A renderer that does not answer within a minute is dropped too, so the next request for its style starts from a fresh map. With tile_size: 256, the zoom 0 tile takes one more renderer per pixel ratio.

Reloading styles costs CPU on every request that misses, so set renderers_per_worker to at least the number of styles times the pixel ratios you serve. Each renderer holds its own memory. To use less, lower renderers_per_worker or static_renderers_per_worker, or list fewer pixel_ratios. A worker renders one image at a time, so its renderers take turns in one graphics context instead of holding one each.

Request scheduling

Each pool keeps one queue of requests. When a worker is free, it picks the next request like this:

  1. If the oldest request has waited 1 s or more, the worker takes it.
  2. Otherwise, it takes the oldest request for a renderer it already holds, looking at the first 64 requests in the queue.
  3. Otherwise, it takes the oldest request if that request has waited at least the switch cost, or if the worker holds no renderer yet.
  4. Otherwise, it waits until the oldest request has waited the switch cost, or until another request arrives or finishes, and starts again at step 1.

The switch cost is the extra time a render takes when the worker first has to load the style or build the renderer. Martin measures it from the renders it serves and keeps it between 5 ms and 500 ms.

Waiting this briefly keeps each worker on the renderers it already holds, so mixed styles and pixel ratios switch renderers far less often. A busy style still spreads to more workers: once its oldest request has waited the switch cost, any free worker takes it. If all requests use the same style and pixel ratio, workers take them oldest first.

FIFO and delay scheduling of the same 18 requests on 3 workers that each hold one renderer. FIFO switches renderers 17 times, delay scheduling 4 times; the average response drops from 223 ms to 128 ms. With one worker that keeps getting requests for its renderer, request #2 for another style waits 1015 ms, then the 1 s cap takes it.liberty @1xliberty-b @1xliberty @2xswitch renderer, 50 msrender 75 ms @1x, 115 ms @2xFIFOa free worker takes the oldest requestswitches368911121314151617avg response-125 ms156 ms171 ms177 ms179 ms182 ms191 ms198 ms205 ms207 ms208 ms213 ms220 ms223 msqueue, oldest first#4#5#6#7#8#9#9#10#10#10#11#11#12#12#12#13#13#13#14#14#14#15#15#15#16#16#16#16#17#17#17#17#17#18#18#18#18worker 1worker 2worker 3#1#2#3#4#5#6#7#8#9#10#11#12#13#14#15#16#17#180100200300400500600700800 msDelay schedulinga free worker takes, in order:switches34avg response-125 ms136 ms134 ms125 ms140 ms140 ms139 ms139 ms139 ms136 ms135 ms131 ms130 ms130 ms128 msqueue, oldest first#4#5#6#7#9#10#10#11#11#11#12#12#13#13#14#15#18worker 1worker 2worker 3443#13#23#32#43#52#62#72#82#92#102#112#122#132#142#152#162#172#180100200300400500600700800 ms1 s cap1 worker holds liberty @1x; its requests arrive every 60 ms, faster than it renders themqueue#2 waits#2 waited0 ms25 ms50 ms75 ms100 ms125 ms150 ms175 ms200 ms225 ms250 ms275 ms300 ms325 ms350 ms375 ms400 ms425 ms450 ms475 ms500 ms525 ms550 ms575 ms600 ms625 ms650 ms675 ms700 ms725 ms750 ms775 ms800 ms825 ms850 ms875 ms900 ms925 ms950 ms975 ms1000 ms1015 msworker 13#11#22#32#42#52#62#72#82#92#102#112#122#132#140100200300400500600700800900100011001200 ms1the oldest request has waited 1 s or more: take it2the queue has requests for a renderer this worker holds: take the oldest of them3the oldest request has waited the switch cost or more, or this worker holds no renderer: take it4else wait, up to the switch cost

Ambient cache

MapLibre Native keeps the tiles, glyphs and sprites its renderers fetch over the network in a cache of its own, in memory and shared by all of them, up to ambient_cache_size_mb MB (MapLibre Native's default of 50 MiB unless configured). Every fetched resource is compressed and stored there, and every fetch looks it up first. A cached resource spares a request only while its Cache-Control says it is fresh, and Martin sends none unless cache_control is set in the configuration file. When the style's sources are Martin's own, the tiles are already a local read away, so ambient_cache_size_mb: 0 saves that work. Keep it for styles that fetch from other servers.

Shader cache

On the CPU, Mesa (llvmpipe) compiles every new renderer's shaders and caches them on disk, in $XDG_CACHE_HOME or $HOME/.cache. Without that cache, creating a renderer, at startup or after one was dropped, takes several times longer.

When neither directory is writable, as in a read-only container, Martin caches shaders in a private directory under $TMPDIR (/tmp unless set) until it exits, and logs that it did. If that is read-only too, it logs a warning and Mesa compiles shaders again for every renderer. For a read-only container, mount a small tmpfs at /tmp (the cache stays under a few MB), or set MESA_SHADER_CACHE_DIR to a writable volume to keep the cache across restarts:

docker run --read-only --tmpfs /tmp ... ghcr.io/maplibre/martin:2.0.0-beta.7-full

Martin leaves MESA_SHADER_CACHE_DIR and MESA_SHADER_CACHE_DISABLE alone when they are set.

Logs

MapLibre logs its own messages under the maplibre_native target, which Martin's default log filter hides. RUST_LOG=martin=info,maplibre_native=warn shows MapLibre's warnings and errors, such as a tile or a glyph range that failed to load.

Static images

Info

Martin currently does not have the same capabilities as Tileserver-GL to layout images. We are working on adding this feature and are very open to contributions if you want to help!

Warning

Static rendering shares the limitations listed above (Linux only, no caching).

Martin can render a single PNG/JPEG/WebP of a style at a chosen camera. The same URL is served by two methods:

GET  /style/{style_id}/static/{camera}/{size}.{ext}
POST /style/{style_id}/static/{camera}/{size}.{ext}

GET returns the base map alone. POST additionally accepts a GeoJSON FeatureCollection in the body, with styling on each feature's properties, and overlays those features on top of the base style for that single render. An empty or missing body is equivalent to GET.

Camera

The {camera} segment chooses what the image looks at:

The four static image camera forms: center and zoom north up, a bearing clockwise from north, a pitch tilting away from straight down, and a bounding box that is fully visible with extra map on the shorter sideNlon,lat,zoomcenter, north upNlon,lat,zoom@bearingdegrees clockwisepitchcameralon,lat,zoom@bearing,pitch0 = straight downbboxminLon,minLat,maxLon,maxLatwhole bbox visible

Info

The whole bounding box is always visible. So if the bbox is [-10°,-1°,10°,1°] and size 500x500 is requested, the image is centered on 0,0 and spans the full 20° of longitude, with extra map above and below the bbox. A bounding box always renders north up and flat.

Size and format

{size}.{ext} follows the WIDTHxHEIGHT[@{scale}x].{ext} pattern, e.g. 800x600.png, 400x300@2x.jpg. Allowed extensions are png, jpg, and webp. Width and height are capped at 2048 px each. The scale is a whole number listed in pixel_ratios (1 if omitted): an unlisted scale is answered with 400 Bad Request, and a fractional or zero scale such as @1.5x or @0x with 404 Not Found.

Overlay body (POST)

The overlay body is a GeoJSON FeatureCollection. Each feature carries its style on properties using MapLibre Style Spec paint/layout property names (circle-*, line-*, fill-*). Any property left unset falls back to MapLibre's own default.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "LineString",
        "coordinates": [[-10, 5], [10, 5]] },
      "properties": { "line-color": "#f00", "line-width": 3, "line-cap": "round" }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [0, 0] },
      "properties": { "circle-color": "#00f", "circle-radius": 8 }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Polygon",
        "coordinates": [[[-5,-5],[5,-5],[5,5],[-5,5],[-5,-5]]] },
      "properties": { "fill-color": "#0a0", "fill-opacity": 0.5 }
    }
  ]
}

How features become layers:

  • Point / MultiPoint -> one circle layer.
  • LineString / MultiLineString -> one line layer.
  • Polygon / MultiPolygon -> a fill layer (unless only line-* properties are set), plus a line layer when any line-* property is present (so a polygon with line-color gets an outline of line-width).
  • GeometryCollection and features with geometry: null are silently skipped.

Anything the server can't make sense of is rejected with 400 Bad Request: a malformed body, a top-level type that isn't FeatureCollection, a member type that isn't Feature, an invalid CSS color, a non-numeric width, or an unknown line-cap/line-join enum value. Unknown property keys on feature.properties are silently ignored, so GeoJSON files that already carry application metadata (id, name, title, description, …) work without modification.

Supported style properties

Every property is optional; an unset property uses the MapLibre Style Spec default.

MapLibre property Applies to MapLibre default
circle-color Point #000000
circle-opacity Point 1
circle-radius Point 5
circle-stroke-color Point #000000
circle-stroke-opacity Point 1
circle-stroke-width Point 0
line-color LineString / Polygon #000000
line-opacity LineString / Polygon 1
line-width LineString / Polygon 1
line-cap LineString / Polygon butt
line-join LineString / Polygon miter
fill-color Polygon #000000
fill-opacity Polygon 1
fill-outline-color Polygon matches fill-color

line-cap is one of butt, round, square; line-join is one of miter, bevel, round. Colors accept any CSS color string.

Range checks are not enforced - *-opacity values outside 0..=1 and negative widths are passed through to MapLibre verbatim.

Out of scope

  • Data-driven expressions on individual feature properties (each feature becomes its own GeoJSON source and layer with literal paint values).
  • Layer types beyond fill / line / circle (no symbol, heatmap, raster, fill-extrusion).
  • Externally-referenced GeoJSON URLs (every feature is inline).
  • Symbol/icon markers (no symbol layer) - use a circle instead.
  • Z-ordering relative to base style layers - all overlay layers are drawn on top of the base style, in feature-array order.

All examples below render the same camera (/static/0,0,2/200x200.png) against the maplibre_demo style, so the visual differences come only from the overlay body.

Line

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [[-10.0, -10.0], [10.0, 10.0]]
    },
    "properties": {
      "line-color": "#95BEFA",
      "line-width": 5,
      "line-cap": "round",
      "line-join": "round"
    }
  }]
}

Pastel-blue diagonal stroke over the demo basemap

Fill

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "Polygon",
      "coordinates": [[
        [-10.0, -10.0], [10.0, -10.0],
        [10.0, 10.0], [-10.0, 10.0],
        [-10.0, -10.0]
      ]]
    },
    "properties": {
      "fill-color": "red",
      "fill-opacity": 1.0
    }
  }]
}

Filled red square polygon

Fill opacity (alpha blending)

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Polygon",
        "coordinates": [[[-40, -20], [10, -20], [10, 20], [-40, 20], [-40, -20]]] },
      "properties": {
        "fill-color": "#285DAA",
        "fill-opacity": 0.5
      }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Polygon",
        "coordinates": [[[-10, -20], [40, -20], [40, 20], [-10, 20], [-10, -20]]] },
      "properties": {
        "fill-color": "#95BEFA",
        "fill-opacity": 0.5
      }
    }
  ]
}

Two semi-transparent brand-color rectangles overlapping

Circle (marker)

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [0.0, 0.0]
    },
    "properties": {
      "circle-color": "#285DAA",
      "circle-radius": 8
    }
  }]
}

Primary-colored circle marker at the equator/prime meridian