Skip to main content

ml2drender (Python)

Open In Colab

Python bindings of ml2drender, a 2D map renderer for MapLibre styles written in pure Rust. It needs no GPU and links no C libraries.

pip install ml2drender

Wheels are built for Linux (x86-64, arm64; glibc), macOS (x86-64, arm64) and Windows (x86-64), for CPython 3.11 and later (abi3).

Usage

A Renderer draws views of a style. It fetches the resources they need (TileJSON, GeoJSON, sprites, tiles, glyph ranges) concurrently with HTTPX. You can override fetching with an async load function.

import asyncio
from pathlib import Path

import httpx
import ml2drender


async def main():
    async with httpx.AsyncClient(follow_redirects=True) as client:
        response = await client.get("https://demotiles.maplibre.org/style.json")
        response.raise_for_status()
        style = response.json()

    renderer = ml2drender.Renderer(style)
    view = ml2drender.View.tile(5, 28, 12, tile_size=512)
    # or a camera: ml2drender.View((139.767, 35.681), zoom=5, width=512, height=512, bearing=0)
    rgba = await renderer.render_view(view)
    width, height = view.pixels
    Path("tile.png").write_bytes(ml2drender.encode_png(rgba, width, height))


asyncio.run(main())

HTTP 404 means a missing resource (an empty vector tile, or a raster tile replaced by its parent). Other HTTP and network errors propagate as HTTPX exceptions. Resource URLs are used exactly as the style writes them, so make glyphs, sprite and TileJSON URLs absolute.

One httpx.AsyncClient is reused across all resource stages of a render, with redirects enabled and HTTPX's default timeouts and connection limits. Resources within each stage are fetched concurrently, without caching. A failed or cancelled render cancels and awaits its outstanding loads before closing the client. Decoding and drawing still run synchronously on the calling thread; the asynchronous API covers resource I/O.

A Renderer keeps the resources and tiles it has decoded, so later views load only what is missing. Renders of one renderer take turns.

For authentication, caching, custom timeouts or non-HTTP sources, pass an async load(url) returning bytes or None for a missing resource. Raise for other failures; the exception propagates out of render_view. The loader must allow concurrent calls and cancellation. For example, inside an async function, to reuse an authenticated client:

async with httpx.AsyncClient(headers={"Authorization": "Bearer ..."}, follow_redirects=True) as client:

    async def load(url):
        response = await client.get(url)
        if response.status_code == 404:
            return None
        response.raise_for_status()
        return response.content

    renderer = ml2drender.Renderer(style, load=load)
    rgba = await renderer.render_view(view)

API

Renderer(style, load=None) A renderer of style (the style JSON as a dict), fixed for its life. load is an optional async load(url) -> bytes | None. Not thread-safe.
await renderer.render_view(view) Non-premultiplied RGBA8 pixels (bytes, row by row) of view, after loading the resources it needs. Requires asyncio.
View(center, zoom, width, height, bearing=0.0, pixel_ratio=1.0, margin=0) A Web Mercator camera. center is (lng, lat) in degrees; zoom is the MapLibre zoom (the world is 512 * 2**zoom CSS pixels wide); bearing is degrees clockwise. The image is width x height CSS pixels, times pixel_ratio in pixels. margin CSS pixels are drawn around it and cropped, so labels near the edge are placed as in a larger map.
View.tile(z, x, y, tile_size=256) The XYZ tile z/x/y, tile_size CSS pixels square.
View.pixels (width, height) of the output in pixels.
renderer.projected(projjson, tile_matrix_set=None) The renderer drawing in a CRS. projjson is the PROJJSON as a dict (for the supported methods, see Projected coordinate reference systems); anything else raises TypeError. tile_matrix_set is the CRS's tile grid, which tiles and cameras need: a TileMatrixSet, or an OGC 2D TileMatrixSet (2.0) as a dict. One renderer can mix CRSs and Web Mercator views, and they share loaded resources.
TileMatrixSet(origin, extent_at_zoom0) MapLibre GL JS's tile grid for a CRS (addProjection): tile 0/0/0 is a square of side extent_at_zoom0 whose top-left corner is origin (min x, max y), in CRS units. Each zoom level splits every tile into four. Use it when the tiles are shown by MapLibre GL JS (pass the grid given to addProjection). Use an OGC 2D TileMatrixSet dict for a published grid, or for one this form cannot describe: scales not halved at each level, tiles not square or not 2^z × 2^z, a fixed list of levels.
await projected.render(box) render_view of a box of the CRS. An unsupported CRS raises RuntimeError.
await projected.render_tile(z, x, y, tile_size=256, pixel_ratio=1.0, margin=0) Tile z/x/y of the CRS's grid, tile_size CSS pixels wide and as high as the grid's tiles are. In an OGC set, z is an index of its tileMatrices. Without a tile_matrix_set it raises TypeError.
await projected.render_view(view) The camera view (a View) in the CRS: the same area as MapLibre GL JS draws with that center, zoom and bearing once the CRS is registered with addProjection. At zoom 0, a tile of the grid's first level (tile 0/0/0 of a TileMatrixSet) is 512 CSS pixels wide. Without a tile_matrix_set it raises TypeError.
ProjectedBox(bbox, size, pixel_ratio=1.0, margin=0) A box of a CRS. bbox is (min_x, min_y, max_x, max_y) in CRS units (degrees for longlat), easting first, with the CRS's y axis up. The image has the box's aspect ratio and size CSS pixels on its long side. The rest is as in View. For a rotated view, use render_view.
ProjectedBox.pixels (width, height) of the output in pixels.
encode_png(rgba, width, height) Lossless PNG.
encode_webp(rgba, width, height) Lossless WebP.
encode_jpeg(rgba, width, height, quality=90) JPEG, flattened over black.

Layers of types the renderer does not draw (fill-extrusion) are skipped; rewrite them in the style beforehand if you want them drawn.

A style that is not a JSON-serializable dict raises TypeError; rendering errors raise RuntimeError. Type hints and docstrings ship with the package (inline Python annotations, _native.pyi and py.typed). The sans-IO steps (needs / provide / render) stay in ml2drender._native.Renderer, which is not a public API.

In a projected CRS, vector layers are drawn with projected vertices; raster, hillshade and color-relief are rendered in Web Mercator and warped:

# utm54n: PROJJSON of EPSG:32654, as a dict
utm = renderer.projected(utm54n, ml2drender.TileMatrixSet((-2_000_000, 6_000_000), 4_000_000))

# a box in CRS units
box = ml2drender.ProjectedBox((300_000, 3_900_000, 500_000, 4_100_000), size=512)
rgba = await utm.render(box)
# a tile of the CRS's grid
rgba = await utm.render_tile(3, 4, 2)
# a camera
rgba = await utm.render_view(ml2drender.View((139.767, 35.681), zoom=6, width=800, height=600, bearing=30))

Reprojected sources for MapLibre GL JS are in the JavaScript package.

License

BSD-3-Clause

Metadata

Release files for ml2drender 0.4.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for ml2drender 0.4.3
File Actions
ml2drender-0.4.3-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for ml2drender-0.4.3-cp311-abi3-win_amd64.whl
ml2drender-0.4.3-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.11 abi3 Linux glibc 2.17+ x86-64 Details for ml2drender-0.4.3-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
ml2drender-0.4.3-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.11 abi3 Linux glibc 2.17+ ARM64 Details for ml2drender-0.4.3-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
ml2drender-0.4.3-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for ml2drender-0.4.3-cp311-abi3-macosx_11_0_arm64.whl
ml2drender-0.4.3-cp311-abi3-macosx_10_12_x86_64.whl CPython 3.11 abi3 macOS 10.12+ x86-64 Details for ml2drender-0.4.3-cp311-abi3-macosx_10_12_x86_64.whl

Total release size: 7.1 MB

Release files / ml2drender-0.4.3-cp311-abi3-win_amd64.whl

Download URL ml2drender-0.4.3-cp311-abi3-win_amd64.whl
Size 1.5 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
c8022d6b29c15c25b39e72dcf75949008b3c13ae20ce4ea2c69daaa07b008d6d
BLAKE2b-256 checksum
How to use checksums
b83a828eb6216d5d122e97942b1be98e706ccc9eb05dfc618e5e8a71bec344e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / ml2drender-0.4.3-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL ml2drender-0.4.3-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 1.5 MB
Tags CPython 3.11 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
d23d80701cb6ad0904a3cae88ecd89a6702832933bc4a66c579676233d45238b
BLAKE2b-256 checksum
How to use checksums
6d71b956f6be36c7baaee45f1cc4b68487d6045f5b5d554dd97834188157c2c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / ml2drender-0.4.3-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL ml2drender-0.4.3-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 1.4 MB
Tags CPython 3.11 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
1a64e952f8e0f1c241723c474d7e29fb5046136816c2704647fddaf8cbaab240
BLAKE2b-256 checksum
How to use checksums
019eb42e06cc8e2e87363271bb77defa70ccf38f330a42d468bb2087afbea8b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / ml2drender-0.4.3-cp311-abi3-macosx_11_0_arm64.whl

Download URL ml2drender-0.4.3-cp311-abi3-macosx_11_0_arm64.whl
Size 1.3 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
c08835ddac4c37590121fd7ed1fcee2d07ad2415044f5bb729e541ccbd72d46d
BLAKE2b-256 checksum
How to use checksums
3c92d260ea6ccfcd21cd5e5ba85c0ad8f24084c1dc1e86b9d8d420823c03c576
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / ml2drender-0.4.3-cp311-abi3-macosx_10_12_x86_64.whl

Download URL ml2drender-0.4.3-cp311-abi3-macosx_10_12_x86_64.whl
Size 1.4 MB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
c38cc9fa2250048d551078564bcf2ab7b93f6d7734fce0263baa38c0816dcf07
BLAKE2b-256 checksum
How to use checksums
b99b9593997ad1b59ab34e8230f52cd40dfc80df21d2de81e6d43a5dcc516861
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for ml2drender 0.4.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for ml2drender-0.4.3-cp311-abi3-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page