Skip to main content

ml2drender (Python)

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

await render(...) fetches the resources a style needs (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.text

    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 ml2drender.render(style, view)
    width, height = view.size
    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.

render is an async function: existing synchronous calls must become await ml2drender.render(...). At a synchronous entry point, use asyncio.run(...); inside an existing asyncio event loop, use await directly.

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. 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

    rgba = await ml2drender.render(style, view, load=load)

To reuse decoded resources across views or manage fetching yourself, drive the sans-IO steps. Resources come in stages, each found from the last, so repeat until nothing is needed. Inside the client context above, replace the render call with:

renderer = ml2drender.Renderer(style, view)
while urls := renderer.needs():
    # Supply each URL's bytes (or None for a missing resource).
    for url in urls:
        renderer.provide(url, await load(url))
rgba = renderer.render()

A Renderer keeps what it has loaded: set_view points it at another camera and the next needs asks only for what is missing.

API

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.size (width, height) of the output in pixels.
await render(style, view, load=None) Non-premultiplied RGBA8 pixels (bytes, row by row) of style (a JSON string) in view. Fetches resources concurrently with HTTPX by default; optionally pass an async load(url) -> bytes | None callable. Requires asyncio.
Renderer(style, view) The steps of render: needs() -> list[str], provide(url, data: bytes | None), render() -> bytes, set_view(view). Not thread-safe.
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.

Invalid styles and rendering errors raise RuntimeError. Type hints and docstrings ship with the package (inline Python annotations, _native.pyi and py.typed).

The Python bindings draw Web Mercator views only. Projected CRSs (PROJJSON) and reprojected sources for MapLibre GL JS are in the JavaScript package.

License

BSD-3-Clause

Metadata

Release files for ml2drender 0.2.0

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.2.0
File Actions
ml2drender-0.2.0-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for ml2drender-0.2.0-cp311-abi3-win_amd64.whl
ml2drender-0.2.0-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.2.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
ml2drender-0.2.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.11 abi3 Linux glibc 2.17+ ARM64 Details for ml2drender-0.2.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
ml2drender-0.2.0-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for ml2drender-0.2.0-cp311-abi3-macosx_11_0_arm64.whl
ml2drender-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl CPython 3.11 abi3 macOS 10.12+ x86-64 Details for ml2drender-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl

Total release size: 6.7 MB

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

Download URL ml2drender-0.2.0-cp311-abi3-win_amd64.whl
Size 1.4 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
0fe1e8a238d4bbc40072405eaf29da8e400a67d6bd11607d73ab2d06777ff869
BLAKE2b-256 checksum
How to use checksums
c0b6dc37c68c6d86d95dfc8494e4b47d2265ef980c2293ecee3029051c4ea524
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 15, 2026.

Transparency log

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

Download URL ml2drender-0.2.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 1.4 MB
Tags CPython 3.11 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
57b8306ad46401d9a7d6660c75315c50df3936030e3283d1a20001b2f7eb5cbc
BLAKE2b-256 checksum
How to use checksums
9abb13976a2cf02a7afc5d987c884d38b9f8094830f1c078361aa5086691fc27
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 15, 2026.

Transparency log

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

Download URL ml2drender-0.2.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 1.3 MB
Tags CPython 3.11 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
2158591ed37e7c97454c24cea88889f36e86b39ff2779253e85ee0fec1303e8a
BLAKE2b-256 checksum
How to use checksums
3cd337f61aabdd072b40b25922e37038b776bded4650c4f7c3faf183fad980bc
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 15, 2026.

Transparency log

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

Download URL ml2drender-0.2.0-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
b47fcf9f1f325bb59f98f455283a84bb248db7d59af88414a8a3248998572afc
BLAKE2b-256 checksum
How to use checksums
556067284d79c12f4e67cafe0e2807e9572d2ae59592e5d8fe6c89c36bcbdc8f
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 15, 2026.

Transparency log

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

Download URL ml2drender-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl
Size 1.3 MB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
0ecdd927004b235b679d032993d048bb016605fe26d551e68003f6911512ee03
BLAKE2b-256 checksum
How to use checksums
ebfbfc3faf19781814b5e7130de8cee484af581848fc91e56cae14d02297a44a
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 15, 2026.

Transparency log

Security for ml2drender 0.2.0

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.2.0-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 15, 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