A 2D map renderer for MapLibre styles, written in Rust. It needs no GPU. It compiles to WebAssembly and runs in browsers, Cloudflare Workers, Deno and Node.js. Node-API and Python bindings are also included.
Live demo · API reference · Quick start · Projected CRSs · Node.js addon · Python (Colab notebook)
wasm32-unknown-unknown and links no C libraries.ml2drender draws flat 2D maps. 3D features (fill-extrusion, terrain, globe, pitch) are out of scope; layers of types it does not draw (fill-extrusion) are skipped, so rewrite them in the style beforehand if you want them drawn (for example as fills). Styles are fixed when a renderer is created: there is no API for changing a style at runtime.
import { MapRenderer } from '@ml2drender/wasm';
const style = await (await fetch('https://demotiles.maplibre.org/style.json')).json();
const renderer = await MapRenderer.init(style);
const image = await renderer.renderView({ center: [139.767, 35.681], zoom: 5, width: 512, height: 512 });
const png = image.toPng(); // or image.toWebp(), image.toJpeg(80); raw RGBA in image.data
The renderer works out which tiles, TileJSON, sprites and glyphs it needs, and fetches them. In browsers (with Vite or similar), the bundled WASM loads automatically. Elsewhere, pass the compiled module as the wasm option: await WebAssembly.compile(readFileSync(new URL(import.meta.resolve('@ml2drender/wasm/renderer.wasm')))) in Node.js and Deno, or import wasm from '@ml2drender/wasm/renderer.wasm' in Cloudflare Workers (Wrangler).
npm install @ml2drender/wasm # WebAssembly: browsers, Node.js, Deno, Workers
npm install @ml2drender/node # native Node.js addon
pip install ml2drender # Python
| Package | Runs in | API |
|---|---|---|
@ml2drender/wasm |
browsers, Node.js, Deno, Cloudflare Workers | Everything below: fetching, Web Mercator and projected views, reprojected sources for GL JS. |
@ml2drender/node |
Node.js (Linux, macOS, Windows) | HTTP fetching by default, with an optional loadResource(url) callback. Web Mercator cameras; boxes, tiles and cameras of a projected CRS. Renders run in parallel off the JS thread. |
ml2drender on PyPI |
CPython 3.11+ (Linux, macOS, Windows) | Async HTTP fetching with HTTPX by default, with an optional async load(url) callback. Web Mercator cameras; boxes, tiles and cameras of a projected CRS. |
All three draw with the same Rust core. To build from source, see Development.
const renderer = await MapRenderer.init(style);
await renderer.renderView({ center: [lng, lat], zoom: 12, bearing: 30, width: 800, height: 600 }); // a camera
await renderer.renderTile({ z: 12, x: 3638, y: 1612 }); // an XYZ tile
await renderer.render({ bbox: [139.5, 35.5, 140, 36], size: 1024 }); // a lng/lat box
In a browser, the pixels of a RenderedImage go straight onto a canvas:
canvas.getContext('2d')!.putImageData(new ImageData(image.data, image.width, image.height), 0, 0);
const utm = renderer.projected({
name: 'EPSG:32654',
projjson: utm54n, // PROJJSON of EPSG:32654
tileMatrixSet: { origin: [-2_000_000, 6_000_000], extentAtZoom0: 4_000_000 },
});
await utm.renderView({ center: [139.767, 35.681], zoom: 6, bearing: 30, width: 800, height: 600 }); // a camera
await utm.render({ bbox: [300_000, 3_900_000, 500_000, 4_100_000], size: 512 }); // a box in CRS units
await utm.renderTile({ z: 3, x: 4, y: 2 }); // a tile of the CRS's grid
renderView takes center as lng/lat and a zoom of the tileMatrixSet grid. It draws the same area as MapLibre GL JS does with that center, zoom and bearing once the CRS is registered with addProjection.
ml2drender returns each source reprojected onto the CRS's tile grid, and MapLibre GL JS draws the original style from those tiles. The CRS is registered with GL JS 6.15's experimental addProjection. GL JS draws the map with WebGL, so it stays interactive and features can be queried.
// Server (e.g. Workers): serve reprojected tiles of each source
const crs = { name: 'EPSG:32654', projjson: utm54n, tileMatrixSet };
const tile = await renderer.projected(crs).getTile({ source, z, x, y }); // MVT, PNG or terrarium PNG
// Browser: register the CRS with GL JS and draw the rewritten style
import { addProjection, Map } from 'maplibre-gl';
import proj4 from 'proj4';
addProjection({ name: crs.name, projection: proj4(crs.projjson), tileMatrixSet: crs.tileMatrixSet });
const glStyle = renderer.projected(crs).toStyle({ tiles: (source) => `https://tiles.example.com/${source}/{z}/{x}/{y}` });
new Map({ container: 'map', style: glStyle });
addProjection takes any forward / inverse pair between lng/lat and CRS coordinates, such as a proj4js converter, which reads PROJJSON. ml2drender draws with its own formulas; for the CRSs of the demo the two agree within a few micrometres. Two things to know:
+proj=geos ...) instead, as the demo does.setProjectionHandler, as the demo does.The @ml2drender/wasm package (WebAssembly). This section is an overview. Every type and option is documented in the API reference.
Takes a style object (the official StyleSpecification type) and loads the WASM. The style is copied when init is called. Resource URLs reach loadResource exactly as the style writes them, so make glyphs and TileJSON urls absolute.
| Option | Default | Description |
|---|---|---|
loadResource |
HTTP fetch |
(url) => Promise<Uint8Array | null>. Fetches tiles, TileJSON, sprites and glyphs. Return null (HTTP 404) for a missing resource and rendering goes on without it; any other failure should reject. Concurrency limits, retries and caching belong here. |
wasm |
bundled WASM | A compiled WebAssembly.Module. Required in Node.js and Cloudflare Workers. |
cache.ttlMs |
300_000 |
How long the renderer inside WASM (decoded tiles, geometry, glyphs) is reused across renders. 0 creates and frees one per render, for the least memory; Infinity never expires. |
Concurrent requests for the same URL are fetched once. Fetched bytes are not cached: rely on the browser's HTTP cache, or cache inside loadResource (for example with the Cache API on Workers).
Renderers with cache.ttlMs: 0 share one WASM instance per module, and WASM memory never shrinks. Overlapping renders each hold their decoded data while they wait for fetches, so peak memory grows with the number of renders in flight. Where memory is tight, limit that number yourself:
import pLimit from 'p-limit';
const limit = pLimit(2); // one limit for every renderer of the module
const image = await limit(() => renderer.renderTile({ z, x, y }));
Each one fetches what it needs and resolves to a RenderedImage of all the style's layers. One renderer can mix views, methods and CRSs, even concurrently, and they share fetched resources.
| Method | Area drawn |
|---|---|
renderView({ center, zoom, bearing?, width, height }) |
A Web Mercator camera. Zoom levels are GL JS's: at zoom 0 the world is 512 CSS px wide. |
renderTile({ z, x, y, tileSize? }) |
An XYZ tile of the Web Mercator grid. tileSize defaults to 256. |
render({ bbox, size }) |
A lng/lat box [west, south, east, north], fitted so that its long side is size px. west > east crosses the antimeridian. |
projected(crs).renderView({ center, zoom, bearing?, width, height }) |
A camera in the CRS, with the same arguments as the Mercator renderView. center is lng/lat. bearing is the angle clockwise from the CRS's y axis of the direction that is up, so at 0 the y axis is up. Zoom levels are those of GL JS with the CRS registered by addProjection: at zoom 0, tile 0/0/0 of the grid is 512 CSS px wide. A center outside the CRS's domain throws a RangeError. |
projected(crs).render({ bbox, size }) |
A box [minX, minY, maxX, maxY] in CRS units (degrees for longlat), y axis up, fitted so that its long side is size px. For a rotated view, use renderView. |
projected(crs).renderTile({ z, x, y, tileSize? }) |
A tile of the CRS's grid. |
All of them also accept two options:
pixelRatio (default 1): the output has CSS px × pixelRatio pixels.margin (default 0): extra CSS px drawn on every side and then cropped. This reduces symbols that go missing because their anchor is just outside a tile.A RenderedImage has:
width and height.data: row-major RGBA pixels in a Uint8ClampedArray.toPng() and toWebp(): a lossless PNG or WebP, encoded inside WASM. WebP is about 30% smaller than PNG.toJpeg(quality): a JPEG encoded inside WASM. quality is 1–100, chroma is subsampled 4:2:0, and transparent pixels become black.Returns a ProjectedRenderer that draws in crs. The original renderer is unchanged. crs has the same shape as a CRS registered with MapLibre GL JS's addProjection:
projjson: the CRS as PROJJSON. render of a box needs nothing else.
tileMatrixSet: required by renderTile, getTile and renderView. A CRS has no tile grid of its own, so tiles and zoom levels mean nothing without one. Either form works:
{ origin: [minX, maxY], extentAtZoom0 }, MapLibre GL JS's grid (addProjection). Tile 0/0/0 is a square of side extentAtZoom0 whose top-left corner is origin. Each zoom level splits every tile into four. x grows to the east and y to the south.WorldCRS84Quad or a national grid with its own scales. z is an index of its tileMatrices, and x/y range over each level's matrixWidth/matrixHeight. pointOfOrigin is in the CRS's axis order (from orderedAxes when it says Lat/Lon or N/E, else from the PROJJSON), and cornerOfOrigin: "bottomLeft" counts rows up. Tiles that are not square render tileSize wide. variableMatrixWidths are not supported. GL JS's addProjection takes only the first form, so tiles from getTile that GL JS reads with toStyle's style must be cut on that grid (getTile itself works with either form).Which to use: the first when the tiles are shown by MapLibre GL JS (pass the tileMatrixSet given to addProjection), with no limit on zoom levels. An OGC set for a published grid (a TileMatrixSet registry, an OGC API - Tiles server, a national grid), or for one the first cannot describe: scales not halved at each level, tiles not square or not 2^z × 2^z, a fixed list of levels. A GL JS grid is also the OGC set whose level z has 512 × 512 px tiles, cellSize = extentAtZoom0 / 512 / 2^z and 2^z × 2^z tiles from origin.
name: the CRS's name in GL JS, required by toStyle only.
Projected renders pick a zoom level from CRS units per CSS px, read on EPSG:3857's scale at the equator (the idea behind OGC scale denominators; for longlat, 360° is one trip around the world). That zoom drives style evaluation and source tile selection. It does not depend on position, so tiles of one grid zoom line up at their edges. At high latitudes the zoom is higher than a Mercator map of the same ground resolution would use. It is not the grid zoom given to renderView: the two agree only when extentAtZoom0 (or the width of a tile of an OGC set's first level) is the width of EPSG:3857's world (about 40,075 km, or 360° for longlat).
Besides renderView, render and renderTile, it has two methods for MapLibre GL JS:
Returns the data of one style source, reprojected into a tile of the grid, as a Promise<Uint8Array> that GL JS reads directly. It is data, not a picture: style layers and filters are not applied. Source data is fetched at the zoom the tile would have if drawn at 512 CSS px.
| Source | Result |
|---|---|
| vector / geojson | An MVT tile with extent 4096 and a buffer of 128 units. All layers, features and properties are kept. A GeoJSON source's layer is named after the source. |
| raster / image | A 512 px PNG, drawn as a raster layer with default paint. Image sources become tiles too. |
| raster-dem | A 512 px PNG of each pixel's elevation, bilinearly interpolated from the source DEM and encoded as terrarium. |
How vector data is reprojected:
Returns the style given to init, rewritten so that GL JS can draw it in CRS crs.name from getTile's tiles.
tiles(sourceId) returns the URL template of each source's tiles ({z}/{x}/{y} of the CRS's grid).source-layer.GL JS evaluates the style at its own zoom on the projected grid, and hillshade slopes come from the tile's zoom. Zoom-dependent styling may therefore look slightly different from ml2drender's own renders.
CRSs are given as PROJJSON (GeographicCRS or ProjectedCRS, or a BoundCRS or CompoundCRS of one, whose datum shift and vertical part are ignored). PROJ strings and WKT are not accepted. You can get PROJJSON from projinfo -o PROJJSON -q EPSG:32654, for example.
The core is a plain Rust crate with no I/O, so it can be wrapped for other hosts. Each host runs the same loop: ask the renderer what it needs, fetch it, provide the bytes, repeat until nothing is needed, then render.
@ml2drender/node, from crates/napi.ml2drender on PyPI, from crates/python (PyO3, abi3).ml2drender crate in crates/core (not on crates.io). Renderer::new(style, View::tile(z, x, y, 256)), then needs() / provide() / render().The MapLibre GL JS render tests are run with GL JS's own comparison: pixelmatch, with each test's tolerances.
| Suite | Result |
|---|---|
| Render tests (1008 applicable) | 991 pass / 17 fail (98.3%) |
| Expression tests (Style Spec, 583) | 581 pass / 2 fail (99.7%) |
The 727 tests out of scope cover 3D, pitch, non-Mercator GL projections and runtime style changes. Main known gaps:
prevAnchor, CrossTileSymbolIndex). Single still images cannot reproduce it.number-format in locales other than en-US. host (JS / Node-API / Python) core::Renderer (sans-IO Rust)
───────────────────────────── ─────────────────────────────
style + view ─────────────────────────────▶ style · expressions
◀───────────── needs(): URLs sources: MVT · GeoJSON · images · sprites
fetch symbols: shaping · placement
provide(url, bytes) ──────────────────────▶ projection · reprojection
◀──────────── render(): RGBA software GL rasterizer
◀─────── export_tile(): MVT/PNG
crates/core is a Rust library with no network, files, async, threads or clocks (sans-IO). It reports the URLs it needs through needs() and works on the bytes the host passes to provide(). What it needs becomes known step by step: tiles first, then the text they contain, then the glyph ranges for that text.crates/wasm exposes the core through a plain C ABI, without wasm-bindgen.packages/ml2drender hides WASM memory handling and the fetch loop behind the TypeScript API.The renderer does not imitate the GPU pipeline. It ports MapLibre's bucket building, shader math and quantization, and rasterizes with the same rules as GL.
pnpm install
pnpm build:wasm # WASM → packages/ml2drender/wasm/
pnpm demo # starts the demo (examples/browser)
pnpm test # Rust unit tests
pnpm typecheck # TypeScript type checks, including the API type tests
pnpm lint # rustfmt, clippy and Ruff
pnpm fixtures # fetches the upstream test data (first time only, about 144 MB)
pnpm test:render # render tests → target/test-report/render/
pnpm test:expression # expression tests → target/test-report/expression/
pnpm build:native # Node-API addon → packages/ml2drender-node/native/
pnpm test:node # Node-API addon tests
pnpm test:python # Python binding tests (uses uv)
pnpm build:docs # API reference (TypeDoc) → target/docs/
pnpm bench base=<dir> head=. # compares WASM performance between two checkouts
crates/core/ rendering engine (sans-IO)
crates/wasm/ C ABI for WebAssembly
crates/napi/ Node-API addon
crates/python/ Python extension
crates/cli/ test runner and native checks
packages/ml2drender/ JavaScript API (WebAssembly)
packages/ml2drender-node/ Node-API addon package
examples/browser/ demo (Vite + MapLibre GL JS)
You need Node.js (version in .node-version), pnpm (version in packageManager), Rust via rustup (version in rust-toolchain.toml), and uv for Python. CI (.github/workflows/build.yml) builds and tests every package on Linux, macOS and Windows; publish.yml publishes to npm and PyPI.
Design constraints and conventions are described in AGENTS.md (in Japanese). Issues and pull requests are welcome. A change to rendering should keep pnpm test:render results unchanged, or explain why they change.
ml2drender was written largely with AI coding agents, using the MapLibre GL JS implementation as the reference.
BSD-3-Clause. Much of the code is ported from MapLibre GL JS and the MapLibre Style Spec (BSD-3-Clause), and from @maplibre/geojson-vt, supercluster, kdbush, polylabel and vt-pbf (MIT / ISC). Their copyright notices and licenses are reproduced in LICENSE. The test data fetched by pnpm fixtures is under its own licenses.