ml2drender 0.1.0__cp311-abi3-win_amd64.whl

ml2drender/__init__.py

@@ -0,0 +1,5 @@
+from .ml2drender import *
+
+__doc__ = ml2drender.__doc__
+if hasattr(ml2drender, "__all__"):
+    __all__ = ml2drender.__all__

ml2drender/__init__.pyi

@@ -0,0 +1,71 @@
+"""MapLibre style 2D renderer (pure Rust, no GPU).
+
+The renderer is sans-IO: it asks for the resources it needs (TileJSON, GeoJSON, sprites, tiles,
+glyph ranges) and the host loads them. :func:`render` runs that loop with a ``load`` callable;
+:class:`Renderer` exposes the steps, for hosts that load concurrently.
+"""
+
+from collections.abc import Callable
+
+class View:
+    """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 in 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 that labels near the edge are placed as in a larger map.
+    """
+
+    def __init__(
+        self,
+        center: tuple[float, float],
+        zoom: float,
+        width: int,
+        height: int,
+        bearing: float = 0.0,
+        pixel_ratio: float = 1.0,
+        margin: int = 0,
+    ) -> None: ...
+    @staticmethod
+    def tile(z: int, x: int, y: int, tile_size: int = 256) -> View:
+        """The XYZ tile ``z/x/y`` of the Web Mercator grid, ``tile_size`` CSS pixels square."""
+    @property
+    def size(self) -> tuple[int, int]:
+        """Output width and height in pixels."""
+
+class Renderer:
+    """A style (JSON string) fixed at creation, drawn for a view once the resources it needs are provided.
+
+    Raises ``RuntimeError`` on an invalid style. Not thread-safe: use it from the thread that created it.
+    """
+
+    def __init__(self, style: str, view: View) -> None: ...
+    def set_view(self, view: View) -> None:
+        """Point the renderer at another camera, keeping the resources and tiles it has."""
+    def needs(self) -> list[str]:
+        """URLs still needed before :meth:`render`.
+
+        Resources come in stages, each found from the last (style sources, then tiles, then glyph
+        ranges), so repeat :meth:`needs` and :meth:`provide` until this is empty.
+        """
+    def provide(self, url: str, data: bytes | None) -> None:
+        """The bytes of ``url``, or None for a missing resource (like HTTP 404: a missing vector
+        tile is empty, a missing raster tile is replaced by its parent)."""
+    def render(self) -> bytes:
+        """Non-premultiplied RGBA8 pixels, row by row (see :attr:`View.size`). Raises ``RuntimeError`` while resources are still needed."""
+
+def render(style: str, view: View, load: Callable[[str], bytes | None]) -> bytes:
+    """Non-premultiplied RGBA8 pixels of ``style`` (JSON string) in ``view``.
+
+    Each resource is loaded with ``load(url)``, which returns its bytes, or None when it is
+    missing (like HTTP 404). Exceptions raised by ``load`` propagate.
+    """
+
+def encode_png(rgba: bytes, width: int, height: int) -> bytes:
+    """Lossless PNG of RGBA8 pixels."""
+
+def encode_webp(rgba: bytes, width: int, height: int) -> bytes:
+    """Lossless WebP of RGBA8 pixels."""
+
+def encode_jpeg(rgba: bytes, width: int, height: int, quality: int = 90) -> bytes:
+    """JPEG of RGBA8 pixels at ``quality`` (1–100), flattened over black."""

ml2drender-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: ml2drender
+Version: 0.1.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+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
+
+The renderer does no I/O. It asks for the resources a style needs (TileJSON, GeoJSON, sprites, tiles, glyph ranges) and you load them. `render` runs that loop with a `load` function:
+
+```python
+import json
+import urllib.error
+import urllib.request
+
+import ml2drender
+
+
+def load(url):
+    try:
+        with urllib.request.urlopen(url) as response:
+            return response.read()
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            return None  # missing: an empty vector tile, a raster tile replaced by its parent
+        raise
+
+
+style = load("https://demotiles.maplibre.org/style.json").decode()
+
+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 = ml2drender.render(style, view, load)
+width, height = view.size
+open("tile.png", "wb").write(ml2drender.encode_png(rgba, width, height))
+```
+
+Resource URLs reach `load` exactly as the style writes them, so make `glyphs`, `sprite` and TileJSON URLs absolute. `load` should return `None` only for a missing resource; raise for other failures (the exception propagates out of `render`).
+
+To load concurrently (for example with asyncio or a thread pool), drive the steps yourself. Resources come in stages, each found from the last, so repeat until nothing is needed:
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+
+renderer = ml2drender.Renderer(style, view)
+with ThreadPoolExecutor(16) as pool:
+    while urls := renderer.needs():
+        for url, data in zip(urls, pool.map(load, urls)):
+            renderer.provide(url, data)
+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. |
+| `render(style, view, load)` | Non-premultiplied RGBA8 pixels (`bytes`, row by row) of `style` (a JSON string) in `view`. |
+| `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 (`ml2drender.pyi`).
+
+The Python bindings draw Web Mercator views only. Projected CRSs (PROJJSON), reprojected sources for MapLibre GL JS and resource fetching are in the [JavaScript package](https://github.com/Kanahiro/ml2drender#javascript-api).
+
+## License
+
+BSD-3-Clause
+

ml2drender-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ml2drender/__init__.py,sha256=URlnh07Ip95698-oNZYP4LyEGwL0DJ-QP6wUGTTElEM,123
+ml2drender/__init__.pyi,sha256=-zYVbyD-aRzKWmULgZM1kM8Puo7mY2JZSCKypayoWXQ,3194
+ml2drender/ml2drender.pyd,sha256=_eFkQds6PTPmM7Y3kkURfD0KoFrL28U-v07QlVPJgNc,3078144
+ml2drender/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ml2drender-0.1.0.dist-info/METADATA,sha256=SoHebX35ZM0X_7MY2Puyp-jpMKNZvOhGRLJzDzuQJt0,4340
+ml2drender-0.1.0.dist-info/WHEEL,sha256=DRguzO_JHkJTcrXDweuHyM66sVwM00caBYZ3J_zMn0w,96
+ml2drender-0.1.0.dist-info/sboms/ml2drender-python.cyclonedx.json,sha256=n3pAQBr1b5ZtdQsrVCpvgpNSGe788f07vPJG08JoqCo,61129
+ml2drender-0.1.0.dist-info/RECORD,,

ml2drender-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.16.0)
+Root-Is-Purelib: false
+Tag: cp311-abi3-win_amd64