Metadata-Version: 2.4
Name: ml2drender
Version: 0.3.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.28.1,<1
Requires-Dist: certifi>=2026.10.19
Summary: MapLibre style 2D renderer in pure Rust, no GPU
License: BSD-3-Clause
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Demo, https://kanahiro.github.io/ml2drender/
Project-URL: Documentation, https://github.com/Kanahiro/ml2drender/tree/main/crates/python
Project-URL: Homepage, https://github.com/Kanahiro/ml2drender

# ml2drender (Python)

Python bindings of [ml2drender](https://github.com/Kanahiro/ml2drender), a 2D map renderer for MapLibre styles written in pure Rust. It needs no GPU and links no C libraries.

```sh
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](https://www.python-httpx.org/async/). You can override fetching with an async `load` function.

```python
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:

```python
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](https://github.com/Kanahiro/ml2drender#projected-coordinate-reference-systems)); anything else raises `TypeError`. `tile_matrix_set` is the CRS's tile grid, which tiles and cameras need. 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. |
| `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. 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, tile 0/0/0 of the grid 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:

```python
# 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](https://github.com/Kanahiro/ml2drender#javascript-api).

## License

BSD-3-Clause

