adafruit-circuitpython-maptiles 1.0.0__py3-none-any.whl

adafruit_circuitpython_maptiles-1.0.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: adafruit-circuitpython-maptiles
+Version: 1.0.0
+Summary: Download and display map tiles from XYZ tile servers such as Open Street Maps. Tiles are cached on SD card.
+Author-email: Adafruit Industries <circuitpython@adafruit.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/adafruit/Adafruit_CircuitPython_MapTiles
+Keywords: adafruit,blinka,circuitpython,micropython,maptiles,slippy,map,tiles,maptiles,maptile,slippymap,openstreetmap,osm
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: Adafruit-Blinka
+Requires-Dist: adafruit-circuitpython-requests
+Requires-Dist: adafruit-circuitpython-connectionmanager
+Provides-Extra: optional
+Requires-Dist: adafruit-circuitpython-esp32spi; extra == "optional"
+Dynamic: license-file
+
+Introduction
+============
+
+
+.. image:: https://readthedocs.org/projects/adafruit-circuitpython-maptiles/badge/?version=latest
+    :target: https://docs.circuitpython.org/projects/maptiles/en/latest/
+    :alt: Documentation Status
+
+
+.. image:: https://raw.githubusercontent.com/adafruit/Adafruit_CircuitPython_Bundle/main/badges/adafruit_discord.svg
+    :target: https://adafru.it/discord
+    :alt: Discord
+
+
+.. image:: https://github.com/adafruit/Adafruit_CircuitPython_MapTiles/workflows/Build%20CI/badge.svg
+    :target: https://github.com/adafruit/Adafruit_CircuitPython_MapTiles/actions
+    :alt: Build Status
+
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+    :target: https://github.com/astral-sh/ruff
+    :alt: Code Style: Ruff
+
+Slippy-map (OpenStreetMap style) tiles for CircuitPython displays: a map
+widget, and a tile cache on the SD card that every program using this
+library shares.
+
+
+Dependencies
+=============
+This driver depends on:
+
+* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+
+Please ensure all dependencies are available on the CircuitPython filesystem.
+This is easily achieved by downloading
+`the Adafruit library and driver bundle <https://circuitpython.org/libraries>`_
+or individual libraries can be installed using
+`circup <https://github.com/adafruit/circup>`_.
+
+
+`Adafruit Fruit Jam <https://www.adafruit.com/product/6200>`_
+
+Installing from PyPI
+=====================
+
+On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
+PyPI <https://pypi.org/project/adafruit-circuitpython-maptiles/>`_.
+To install for current user:
+
+.. code-block:: shell
+
+    pip3 install adafruit-circuitpython-maptiles
+
+To install system-wide (this may be required in some cases):
+
+.. code-block:: shell
+
+    sudo pip3 install adafruit-circuitpython-maptiles
+
+To install in a virtual environment in your current project:
+
+.. code-block:: shell
+
+    mkdir project-name && cd project-name
+    python3 -m venv .venv
+    source .env/bin/activate
+    pip3 install adafruit-circuitpython-maptiles
+
+Installing to a Connected CircuitPython Device with Circup
+==========================================================
+
+Make sure that you have ``circup`` installed in your Python environment.
+Install it with the following command if necessary:
+
+.. code-block:: shell
+
+    pip3 install circup
+
+With ``circup`` installed and your CircuitPython device connected use the
+following command to install:
+
+.. code-block:: shell
+
+    circup install adafruit_maptiles
+
+Or the following command to update an existing version:
+
+.. code-block:: shell
+
+    circup update
+
+Usage Example
+=============
+
+.. code-block:: python
+
+    import sys
+
+    import supervisor
+    from adafruit_fruitjam.peripherals import request_display_config
+
+    from adafruit_maptiles.cache import TileCache
+    from adafruit_maptiles.map_view import MapView
+
+    CENTRE = (40.7128, -74.0060)  # (lat, lon)
+    ZOOM = 12
+
+    request_display_config(320, 240, color_depth=8)
+    display = supervisor.runtime.display
+    display.auto_refresh = False
+
+    # Name your program in the User-Agent: the OpenStreetMap tile servers ask for it.
+    cache = TileCache(user_agent="maptiles_simpletest/1.0 CircuitPython")
+    view = MapView(display.width, display.height, CENTRE, ZOOM, cache=cache)
+    display.root_group = view
+
+
+    def show():
+        view.update(progress=lambda done, total: print(f"tile {done + 1} of {total}"))
+        if view.net_error:
+            print("Download failed:", view.net_error)
+        view.redraw()  # the tiles and the scale bar and credit; draw markers before dirty()
+        lat, lon = view.centre
+        x, y = view.xy(lat, lon)
+        view.cross(x, y)
+        view.dirty()
+        display.refresh()
+
+
+    show()
+    while True:
+        if supervisor.runtime.serial_bytes_available:
+            key = sys.stdin.read(1)
+            if key in "wasd":
+                view.pan(*{"w": (0, -0.25), "a": (-0.25, 0), "s": (0, 0.25), "d": (0.25, 0)}[key])
+            elif key in "+=":
+                view.zoom_in()
+            elif key == "-":
+                view.zoom_out()
+            else:
+                continue
+            show()
+
+
+Documentation
+=============
+API documentation for this library can be found on `Read the Docs <https://docs.circuitpython.org/projects/maptiles/en/latest/>`_.
+
+For information on building library documentation, please check out
+`this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.
+
+Contributing
+============
+
+Contributions are welcome! Please read our `Code of Conduct
+<https://github.com/adafruit/Adafruit_CircuitPython_MapTiles/blob/HEAD/CODE_OF_CONDUCT.md>`_
+before contributing to help this project stay welcoming.

adafruit_circuitpython_maptiles-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+adafruit_circuitpython_maptiles-1.0.0.dist-info/licenses/LICENSE,sha256=IrDmGxfX4xdm-jZka6acotFMss63SMR3pHWyFp7jA3o,1100
+adafruit_maptiles/__init__.py,sha256=bbBnTFO_Ss1FLKVNVjEnzh61hDmi1vYGfmoZN7E-d_s,3458
+adafruit_maptiles/cache.py,sha256=h2jaWt4F60mh05NAok4-TjG2X3mYG4Jjf4sVvz6Dzgk,10253
+adafruit_maptiles/map_view.py,sha256=NieAEcd44V-s7fOW8IooO5Vr2T7sCLFJKK-So1rq-MQ,19465
+adafruit_maptiles/png.py,sha256=nThOWXVxWj6ESHqqq05Pir6cXwz1CibvGdj32kQMjKY,5728
+adafruit_circuitpython_maptiles-1.0.0.dist-info/METADATA,sha256=TN20_mNsPYWQzp7G3uk9Qt7wIZtxQFySbX1VQGxWWl8,5905
+adafruit_circuitpython_maptiles-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+adafruit_circuitpython_maptiles-1.0.0.dist-info/top_level.txt,sha256=2G_NVbS9ck3MTtwBqfntHAxIf-8c9rLG9eJNpLtED6o,18
+adafruit_circuitpython_maptiles-1.0.0.dist-info/RECORD,,

adafruit_circuitpython_maptiles-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

adafruit_circuitpython_maptiles-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Tim Cocks for Adafruit Industries
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adafruit_circuitpython_maptiles-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+adafruit_maptiles

adafruit_maptiles/__init__.py

@@ -0,0 +1,104 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tim Cocks for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`adafruit_maptiles`
+================================================================================
+
+Slippy-map (OpenStreetMap style) tiles for CircuitPython displays: a map
+widget, and a tile cache on the SD card that every program using this
+library shares.
+
+* Author(s): Tim Cocks
+
+The package:
+
+* :mod:`adafruit_maptiles` (this module): the tile maths (Web Mercator,
+  256x256 tiles, ``{z}/{x}/{y}``) and the RGB332 colours the cached tiles
+  are stored in. Plain Python.
+* :mod:`adafruit_maptiles.png`: PNG -> 8-bit RGB332 BMP conversion. Plain
+  Python (``zlib``).
+* :mod:`adafruit_maptiles.cache`: :class:`~adafruit_maptiles.cache.TileCache`,
+  the shared cache (``/sd/tiles/<source>/{z}/{x}/{y}.bmp``), downloads, and
+  mounting the SD card.
+* :mod:`adafruit_maptiles.map_view`: :class:`~adafruit_maptiles.map_view.MapView`,
+  a :class:`displayio.Group` showing the map, with helpers for drawing on
+  it.
+
+Implementation Notes
+--------------------
+
+**Hardware:**
+
+* A board with an SD card slot (``board.SD_*`` pins, or a card mounted at
+  ``/sd`` by the program) and a network connection, e.g. the
+  `Adafruit Fruit Jam <https://www.adafruit.com/product/6200>`_.
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://circuitpython.org/downloads
+* Adafruit's Requests library: https://github.com/adafruit/Adafruit_CircuitPython_Requests
+* Adafruit's Connection Manager library:
+  https://github.com/adafruit/Adafruit_CircuitPython_ConnectionManager
+* Adafruit's ESP32SPI library (boards with an ESP32 co-processor, such as
+  the Fruit Jam): https://github.com/adafruit/Adafruit_CircuitPython_ESP32SPI
+"""
+
+import math
+
+__version__ = "1.0.0"
+__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_MapTiles.git"
+
+TILE = 256
+"""Tile width and height, pixels."""
+
+
+# ----------------------------------------------------------------- maths
+
+
+def world_x(lon, zoom):
+    """Longitude -> x in pixels on the whole map at this zoom."""
+    return (lon + 180.0) / 360.0 * (TILE << zoom)
+
+
+def mercator(lat):
+    """Latitude -> Mercator y, -0.5 (85.05N) .. 0.5 (85.05S)."""
+    lat = max(-85.05, min(85.05, lat))
+    s = math.sin(math.radians(lat))
+    return -math.log((1 + s) / (1 - s)) / (4 * math.pi)
+
+
+def unmercator(y):
+    """Mercator y -> latitude (:func:`mercator`'s inverse)."""
+    k = math.exp(-4 * math.pi * max(-0.5, min(0.5, y)))
+    return math.degrees(math.asin((k - 1) / (k + 1)))
+
+
+def world_y(lat, zoom):
+    """Latitude -> y in pixels on the whole map at this zoom."""
+    return (0.5 + mercator(lat)) * (TILE << zoom)
+
+
+def tile_xy(lat, lon, zoom):
+    """The ``(x, y)`` numbers of the tile that (lat, lon) is on."""
+    n = 1 << zoom
+    return int(world_x(lon, zoom)) // TILE % n, min(n - 1, int(world_y(lat, zoom)) // TILE)
+
+
+def metres_per_pixel(lat, zoom):
+    """Ground distance across one map pixel at this latitude and zoom."""
+    return 156543.034 * math.cos(math.radians(lat)) / (1 << zoom)
+
+
+# ------------------------------------------------------------ colours
+
+
+def rgb332(r, g, b):
+    """8-bit r, g, b -> an RGB332 value (the cached tiles' pixels)."""
+    return (r & 0xE0) | (g & 0xE0) >> 3 | b >> 6
+
+
+def rgb332_colour(v):
+    """RGB332 value -> 0xRRGGBB."""
+    return ((v >> 5) * 255 // 7) << 16 | ((v >> 2 & 7) * 255 // 7) << 8 | (v & 3) * 85

adafruit_maptiles/cache.py

@@ -0,0 +1,286 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tim Cocks for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`adafruit_maptiles.cache`
+================================================================================
+
+The tile cache on the SD card, shared by every program that uses this
+library: a tile downloaded once (by any of them) is there for all of
+them. Each tile source has its own folder, in the source's own
+``{z}/{x}/{y}`` layout::
+
+    /sd/tiles/osm/9/122/196.png     as downloaded
+    /sd/tiles/osm/9/122/196.bmp     the same, 8-bit RGB332, rows top-down
+
+Only the BMP is read to draw the map (:mod:`adafruit_maptiles.png`).
+Downloads and conversions each take seconds, so they happen once per
+tile; files are written under a temporary name and renamed when complete,
+so a reset part way leaves no broken tile. Tiles copied to the card from
+a PC (PNG or BMP, same layout) are used as they are.
+
+The default source is OpenStreetMap's standard tile server. Its usage
+policy (https://operations.osmfoundation.org/policies/tiles/) asks for a
+User-Agent that identifies the program, that downloaded tiles are kept
+(which the cache does) and that the map shows "(C) OpenStreetMap
+contributors" (:class:`~adafruit_maptiles.map_view.MapView` does). Pass
+your program's name as ``user_agent``.
+
+Plain Python apart from mounting the card and downloading.
+"""
+
+import os
+
+from adafruit_maptiles import TILE
+from adafruit_maptiles.png import png_to_bmp
+
+CACHE_ROOT = "/sd/tiles"
+"""Where every program's tiles go, a folder per source."""
+
+USER_AGENT = "adafruit_maptiles/1.0 CircuitPython"
+
+
+class TileSource:
+    """Where tiles come from.
+
+    :param str name: the cache folder's name (under ``CACHE_ROOT``); one per
+        tile style, shared by everything that uses that style
+    :param str url: the tile URL, with ``{z}``, ``{x}`` and ``{y}``
+    :param str credit: the attribution that must be shown on the map
+    :param int max_zoom: the closest zoom the server has
+    """
+
+    def __init__(self, name, url, credit, max_zoom=19):
+        self.name = name
+        self.url = url
+        self.credit = credit
+        self.max_zoom = max_zoom
+
+
+OSM = TileSource(
+    "osm", "https://tile.openstreetmap.org/{z}/{x}/{y}.png", "(C) OpenStreetMap contributors"
+)
+"""OpenStreetMap's standard tiles (the default)."""
+
+
+def _exists(path):
+    try:
+        os.stat(path)
+        return True
+    except OSError:
+        return False
+
+
+def _makedirs(path):
+    at = ""
+    for part in path.strip("/").split("/"):
+        at += "/" + part
+        try:
+            os.mkdir(at)
+        except OSError:
+            pass
+
+
+def mount_sd(path="/sd"):
+    """True if a card is mounted at path, mounting the board's SD card
+    (``board.SD_SCK``, ``SD_MOSI``, ``SD_MISO``, ``SD_CS``, or ``board.SPI()``
+    and ``SD_CS`` on boards without SD bus pins) there if the supervisor or
+    the program has not already."""
+    try:
+        if os.statvfs(path) != os.statvfs("/"):
+            return True
+    except OSError:
+        pass
+    spi = None  # a bus made here, released if the card does not mount
+    try:
+        import board  # noqa: PLC0415
+        import busio  # noqa: PLC0415
+        import sdcardio  # noqa: PLC0415
+        import storage  # noqa: PLC0415
+
+        if hasattr(board, "SD_SCK"):
+            spi = busio.SPI(board.SD_SCK, board.SD_MOSI, board.SD_MISO)
+            bus = spi
+        else:
+            # The card shares the board's SPI bus (e.g. PyPortal, Metro
+            # ESP32-S3) with other devices, so the bus is left as it is.
+            bus = board.SPI()
+        storage.mount(storage.VfsFat(sdcardio.SDCard(bus, board.SD_CS)), path)
+        return os.statvfs(path) != os.statvfs("/")
+    except Exception as error:
+        if spi is not None:
+            try:
+                spi.deinit()
+            except Exception:
+                pass
+        print("SD_MOUNT_ERROR", type(error).__name__, error)
+        return False
+
+
+_radio = None
+_session = None
+
+
+def _find_radio():
+    """The board's native Wi-Fi (``wifi.radio``), otherwise its ESP32
+    co-processor: shared through the core when the core is managing it (web
+    workflow), otherwise driven over the ``board.ESP_*`` pins from here."""
+    try:
+        import wifi  # noqa: PLC0415
+
+        return wifi.radio
+    except ImportError:
+        pass
+    from adafruit_esp32spi import adafruit_esp32spi  # noqa: PLC0415
+
+    try:
+        import _airlift  # noqa: PLC0415, PLC2701
+
+        shared = _airlift.active()
+    except ImportError:
+        shared = False
+    if shared:
+        return adafruit_esp32spi.ESP_SPIcontrol()
+    import board  # noqa: PLC0415
+    from digitalio import DigitalInOut  # noqa: PLC0415
+
+    gpio0 = getattr(board, "ESP_GPIO0", None)
+    return adafruit_esp32spi.ESP_SPIcontrol(
+        board.SPI(),
+        DigitalInOut(board.ESP_CS),
+        DigitalInOut(board.ESP_BUSY),
+        DigitalInOut(board.ESP_RESET),
+        DigitalInOut(gpio0) if gpio0 else None,
+    )
+
+
+def default_session():
+    """An ``adafruit_requests`` session, made once and shared by every cache:
+    over the board's native Wi-Fi (``wifi.radio``), otherwise through an
+    ESP32 co-processor (``adafruit_esp32spi``; on the Fruit Jam the core
+    shares its ESP32-C6 when web workflow is running). If the radio is not
+    connected yet, it joins ``CIRCUITPY_WIFI_SSID`` with
+    ``CIRCUITPY_WIFI_PASSWORD`` from settings.toml."""
+    global _radio, _session  # noqa: PLW0603
+    if _session is None:
+        import adafruit_connection_manager  # noqa: PLC0415
+        import adafruit_requests  # noqa: PLC0415
+
+        if _radio is None:
+            _radio = _find_radio()
+        if not _radio.connected:
+            ssid = os.getenv("CIRCUITPY_WIFI_SSID")
+            if not ssid:
+                raise RuntimeError("Wi-Fi is not connected, and CIRCUITPY_WIFI_SSID is not set")
+            _radio.connect(ssid, os.getenv("CIRCUITPY_WIFI_PASSWORD", ""))
+        pool = adafruit_connection_manager.get_radio_socketpool(_radio)
+        ssl = adafruit_connection_manager.get_radio_ssl_context(_radio)
+        _session = adafruit_requests.Session(pool, ssl)
+    return _session
+
+
+class TileCache:
+    """The cached tiles of one source, fetched when missing.
+
+    :param TileSource source: where tiles come from (default: :data:`OSM`)
+    :param str root: the cache's top folder (default: :data:`CACHE_ROOT`);
+        a root on ``/sd`` mounts the SD card when the cache is first used
+    :param str user_agent: identifies the program to the tile server
+    :param session: an ``adafruit_requests.Session`` to download with
+        (default: :func:`default_session`, made at the first download)
+    """
+
+    def __init__(self, source=OSM, root=CACHE_ROOT, user_agent=USER_AGENT, session=None):
+        self.source = source
+        root = root.rstrip("/")
+        self.folder = f"{root}/{source.name}"
+        self.user_agent = user_agent
+        self._session = session
+        self._mounted = None
+        self.fetched = 0
+        """Tiles downloaded since the cache was made."""
+        self.converted = 0
+        """Tiles converted to BMP since the cache was made."""
+
+    @property
+    def available(self):
+        """True if the card the cache is on is there (mounting it the first
+        time, if needed)."""
+        if self._mounted is None:
+            self._mounted = mount_sd() if self.folder.startswith("/sd/") else True
+        return self._mounted
+
+    def path(self, z, x, y, ext="bmp"):
+        """The file of tile (z, x, y): ``ext`` ``"bmp"`` or ``"png"``."""
+        return f"{self.folder}/{z}/{x}/{y}.{ext}"
+
+    def ready(self, z, x, y):
+        """True if the tile's BMP is in the cache."""
+        return self.available and _exists(self.path(z, x, y))
+
+    def has_png(self, z, x, y):
+        """True if the tile's PNG is in the cache (no download needed)."""
+        return self.available and _exists(self.path(z, x, y, "png"))
+
+    def open(self, z, x, y):
+        """The tile's BMP, open for reading (pixels from ``png.BMP_HEADER``),
+        or None if it is not in the cache."""
+        try:
+            return open(self.path(z, x, y), "rb")
+        except OSError:
+            return None
+
+    def session(self):
+        """The ``adafruit_requests`` session downloads use."""
+        if self._session is None:
+            self._session = default_session()
+        return self._session
+
+    def fetch(self, z, x, y):
+        """Download the tile's PNG to the cache; returns its bytes."""
+        url = self.source.url.format(z=z, x=x, y=y)
+        r = self.session().get(url, headers={"User-Agent": self.user_agent})
+        try:
+            if r.status_code != 200:
+                raise OSError(f"HTTP {r.status_code} for {url}")
+            data = r.content
+        finally:
+            r.close()
+        path = self.path(z, x, y, "png")
+        _makedirs(path[: path.rfind("/")])
+        with open(path + ".tmp", "wb") as f:
+            f.write(data)
+        os.rename(path + ".tmp", path)
+        self.fetched += 1
+        return data
+
+    def convert(self, z, x, y, data=None):
+        """The tile's PNG (data, or the cached file) -> its BMP."""
+        if data is None:
+            with open(self.path(z, x, y, "png"), "rb") as f:
+                data = f.read()
+        path = self.path(z, x, y)
+        _makedirs(path[: path.rfind("/")])
+        with open(path + ".tmp", "wb") as f:
+            size = png_to_bmp(data, f)
+        if size != (TILE, TILE):
+            os.remove(path + ".tmp")
+            raise ValueError(f"tile is {size[0]}x{size[1]}")
+        os.rename(path + ".tmp", path)
+        self.converted += 1
+
+    def get(self, z, x, y):
+        """Make sure the tile's BMP is in the cache: downloads the PNG if it
+        is not there either, then converts it. Seconds. Returns True if it
+        downloaded.
+
+        :raises OSError: no card, no network, or the server refused
+        :raises ValueError: the PNG cannot be read
+        """
+        if self.ready(z, x, y):
+            return False
+        if not self.available:
+            raise OSError("no SD card for the tile cache")
+        fetch = not self.has_png(z, x, y)
+        self.convert(z, x, y, self.fetch(z, x, y) if fetch else None)
+        return fetch

adafruit_maptiles/map_view.py

@@ -0,0 +1,509 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tim Cocks for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`adafruit_maptiles.map_view`
+================================================================================
+
+:class:`MapView`, a :class:`displayio.Group` showing a slippy map from the
+shared tile cache (:mod:`adafruit_maptiles.cache`), and the pieces for
+drawing over it.
+
+The map is one 256-colour bitmap (:attr:`MapView.bitmap`, palette: the
+RGB332 colours), over a second one holding just the tiles (the
+underlay). Tiles are read from their BMPs a strip of rows at a time into
+the underlay. Drawing a frame, the program:
+
+1. copies the underlay back over the map (:meth:`MapView.restore`, of the
+   whole map or one rectangle),
+2. draws its markers with :meth:`MapView.fill`, :meth:`MapView.line`,
+   :meth:`MapView.blit` and :meth:`MapView.cross` (clipped to the map, or
+   to the rectangle), at :meth:`MapView.xy` of their positions,
+3. draws the scale bar and the tiles' credit (:meth:`MapView.draw_legend`),
+4. marks the bitmap changed (:meth:`MapView.dirty`) and refreshes the display.
+
+Colours are RGB332 values (:func:`adafruit_maptiles.rgb332`); on an 8-bit
+``picodvi`` framebuffer they are the framebuffer's own.
+
+Missing tiles are grey until they are fetched. Setting the view queues
+them (:attr:`MapView.missing`, nearest the centre first);
+:meth:`MapView.fetch_step` downloads and converts one (seconds: a
+program that must stay responsive calls it when it can wait), then
+:meth:`MapView.load` puts it on the map. Programs that do not mind
+waiting call :meth:`MapView.update` instead.
+
+Loading: :meth:`MapView.load_step` reads one strip of rows (a few ms),
+:meth:`MapView.load` all the strips still to read.
+
+CircuitPython note: assigning to a slice of a memoryview of a big buffer
+moves the buffer's whole tail, so pixels are copied with ``bitmaptools``,
+never by slices.
+"""
+
+import bitmaptools
+import displayio
+import terminalio
+
+from adafruit_maptiles import (
+    TILE,
+    mercator,
+    metres_per_pixel,
+    rgb332_colour,
+    unmercator,
+    world_x,
+    world_y,
+)
+from adafruit_maptiles.cache import TileCache
+from adafruit_maptiles.png import BMP_HEADER
+
+# Colours are RGB332 values.
+BLACK = 0x00
+WHITE = 0xFF
+NO_TILE = 0xB6
+"""Where a tile is missing."""
+WAITING = 0x49
+"""The whole map, while it has no centre."""
+
+_palette = None
+
+
+def palette():
+    """The RGB332 palette (256 colours), shared by every map."""
+    global _palette  # noqa: PLW0603
+    if _palette is None:
+        _palette = displayio.Palette(256)
+        for v in range(256):
+            _palette[v] = rgb332_colour(v)
+    return _palette
+
+
+_glyphs = {}
+
+
+def text_bitmap(text, background, width=None, outline=False):
+    """text on background in terminalio's font (6x12; 1 pixel margin), as a
+    256-colour bitmap to :meth:`MapView.blit` onto the map. With outline:
+    a black border, 14 pixels high and 2 pixels either side of the text.
+    width: wider than the text (the text goes on the right)."""
+    # (a glyph's own blank column is on its right)
+    b = displayio.Bitmap(width or 6 * len(text) + (5 if outline else 2), 14 if outline else 13, 256)
+    if outline:
+        b.fill(BLACK)
+        bitmaptools.fill_region(b, 1, 1, b.width - 1, b.height - 1, background)
+    else:
+        b.fill(background)
+    for k, ch in enumerate(text):
+        g = _glyphs.get(ch)
+        if g is None:
+            glyph = terminalio.FONT.get_glyph(ord(ch))
+            g = _glyphs[ch] = glyph.tile_index * 6 if glyph else -1
+        if g >= 0:
+            bitmaptools.blit(
+                b,
+                terminalio.FONT.bitmap,
+                b.width - 6 * len(text) - (2 if outline else 1) + 6 * k,
+                1,
+                x1=g,
+                y1=0,
+                x2=g + 6,
+                y2=12,
+                skip_source_index=0,
+            )
+    return b
+
+
+def overlaps(a, b):
+    """True if rectangles a and b, ``(x1, y1, x2, y2)``, overlap."""
+    return a[0] < b[2] and b[0] < a[2] and a[1] < b[3] and b[1] < a[3]
+
+
+class MapView(displayio.Group):  # noqa: PLR0904
+    """A slippy map, width x height pixels, centred on centre at zoom.
+
+    :param int width: the map's width in pixels
+    :param int height: the map's height in pixels
+    :param tuple centre: ``(lat, lon)``, or None for no map yet (the map is
+        dark grey until :attr:`centre` is set)
+    :param int zoom: 0 (the world in one tile) .. ``zooms[1]``
+    :param TileCache cache: where the tiles come from (default: a
+        :class:`~adafruit_maptiles.cache.TileCache` of OpenStreetMap
+        tiles in the shared cache)
+    :param tuple zooms: ``(closest out, closest in)`` that :attr:`zoom` keeps to
+        (default: 0 .. the source's maximum)
+    :param int x: the map's position in its parent group
+    :param int y: the map's position in its parent group
+    :param int strip: rows read per :meth:`load_step`
+    :param bool scale_bar: draw a scale bar at the bottom left
+    :param bool credit: draw the source's credit at the bottom right (the
+        OpenStreetMap tiles' usage policy requires it)
+    """
+
+    def __init__(  # noqa: PLR0913, PLR0917
+        self,
+        width,
+        height,
+        centre=None,
+        zoom=8,
+        cache=None,
+        zooms=None,
+        x=0,
+        y=0,
+        strip=8,
+        scale_bar=True,
+        credit=True,
+    ):
+        super().__init__(x=x, y=y)
+        self.width = width
+        self.height = height
+        self.cache = cache or TileCache()
+        self.zooms = zooms or (0, self.cache.source.max_zoom)
+        self.strip = strip
+        self.bitmap = displayio.Bitmap(width, height, 256)
+        """The map as shown: the tiles and what is drawn over them."""
+        self.under = displayio.Bitmap(width, height, 256)
+        """Just the tiles."""
+        self._rows = displayio.Bitmap(TILE, strip, 256)  # a tile's rows, read from its file
+        self._rows_mv = memoryview(self._rows)
+        self.append(displayio.TileGrid(self.bitmap, pixel_shader=palette()))
+        self.credit = text_bitmap(self.cache.source.credit, WHITE) if credit else None
+        self._show_scale = scale_bar
+        self.scale_bar = None
+        """The scale bar's bitmap (None: no scale bar, or no centre)."""
+        self.missing = []
+        """``(z, x, y)`` tiles to fetch, nearest the centre first."""
+        self.net_error = None
+        """Why the last download failed (until the view changes), or None."""
+        self._todo = []  # strips to (re)load
+        self._files = {}  # (x, y) -> open tile BMP, or None, while strips load
+        self._centre = centre
+        self._zoom = self._clamp(zoom)
+        self.set_view()
+
+    # ------------------------------------------------------------ view
+
+    def _clamp(self, zoom):
+        return max(self.zooms[0], min(self.zooms[1], zoom))
+
+    @property
+    def centre(self):
+        """The map's centre, ``(lat, lon)``, or None. Setting it moves the map."""
+        return self._centre
+
+    @centre.setter
+    def centre(self, centre):
+        self.set_view(centre=centre)
+
+    @property
+    def zoom(self):
+        """The zoom (kept to :attr:`zooms`). Setting it zooms the map."""
+        return self._zoom
+
+    @zoom.setter
+    def zoom(self, zoom):
+        self.set_view(zoom=zoom)
+
+    def set_view(self, centre=None, zoom=None):
+        """Move the map to centre and / or zoom (or just reload it): queues
+        the tiles not in the cache (:attr:`missing`) and every strip for
+        loading. Nothing changes on the screen until :meth:`load` (or
+        :meth:`load_step`) and a redraw."""
+        if centre is not None:
+            self._centre = (centre[0], centre[1])
+        if zoom is not None:
+            self._zoom = self._clamp(zoom)
+        self._close_files()
+        self._todo = list(range((self.height + self.strip - 1) // self.strip))
+        self.missing = []
+        self.net_error = None
+        if self._centre is None:
+            self.scale_bar = None
+            return
+        z = self._zoom
+        lat, lon = self._centre
+        w, h = self.width, self.height
+        self.x0 = int(world_x(lon, z)) - w // 2
+        self.y0 = int(world_y(lat, z)) - h // 2
+        self.clon = lon
+        self.cmerc = mercator(lat)
+        self.world = TILE << z
+        n = 1 << z
+        ctx, cty = (self.x0 + w // 2) >> 8, (self.y0 + h // 2) >> 8
+        need = []
+        seen = set()
+        for ty in range(self.y0 >> 8, ((self.y0 + h - 1) >> 8) + 1):
+            for tx in range(self.x0 >> 8, ((self.x0 + w - 1) >> 8) + 1):
+                # (at low zooms the map wraps round: the same tile twice)
+                if 0 <= ty < n and (tx % n, ty) not in seen:
+                    seen.add((tx % n, ty))
+                    if not self.cache.ready(z, tx % n, ty):
+                        need.append(((tx - ctx) ** 2 + (ty - cty) ** 2, tx % n, ty))
+        self.missing = [(z, x, y) for _, x, y in sorted(need)]
+        self.scale_bar = self._make_scale(lat, z) if self._show_scale else None
+
+    @staticmethod
+    def _make_scale(lat, z):
+        """The scale bar: the longest 1, 2 or 5 x 10^k that fits in 80 pixels."""
+        mpp = metres_per_pixel(lat, z)
+        step = 1
+        while step * 10 <= mpp * 80:
+            step *= 10
+        metres = max(m for m in (step, 2 * step, 5 * step) if m <= mpp * 80 or m == step)
+        px = max(1, int(metres / mpp))
+        text = f"{metres // 1000} km" if metres >= 1000 else f"{metres} m"
+        scale = text_bitmap(text, WHITE, px + 8 + 6 * len(text))
+        bitmaptools.fill_region(scale, 3, 9, 3 + px, 11, BLACK)
+        bitmaptools.fill_region(scale, 3, 4, 4, 11, BLACK)
+        bitmaptools.fill_region(scale, 2 + px, 4, 3 + px, 11, BLACK)
+        return scale
+
+    def xy(self, lat, lon):
+        """(lat, lon) -> ``(x, y)`` on the map, in pixels (outside
+        0 .. width, 0 .. height when it is off the map)."""
+        return (
+            self.width // 2 + round((lon - self.clon) / 360 * self.world),
+            self.height // 2 + round((mercator(lat) - self.cmerc) * self.world),
+        )
+
+    def latlon(self, x, y):
+        """``(x, y)`` on the map -> (lat, lon)."""
+        lon = self.clon + (x - self.width // 2) / self.world * 360
+        lat = unmercator(self.cmerc + (y - self.height // 2) / self.world)
+        return lat, (lon + 540) % 360 - 180
+
+    def pan(self, dx, dy):
+        """Move the map by dx widths and dy heights (e.g. ``pan(0.25, 0)``:
+        a quarter of the map to the right)."""
+        if self._centre is not None:
+            self.centre = self.latlon(
+                self.width // 2 + dx * self.width, self.height // 2 + dy * self.height
+            )
+
+    def zoom_in(self):
+        """One zoom closer; True if the zoom changed."""
+        z = self._zoom
+        self.zoom = z + 1
+        return self._zoom != z
+
+    def zoom_out(self):
+        """One zoom further out; True if the zoom changed."""
+        z = self._zoom
+        self.zoom = z - 1
+        return self._zoom != z
+
+    def fit(self, points, max_zoom=None, margin=24):
+        """Centre the map on the ``(lat, lon)`` points, at the closest zoom
+        (up to max_zoom) that shows them all, margin pixels inside the map."""
+        lons = [lon for _, lon in points]
+        ys = [mercator(lat) for lat, _ in points]
+        z = self._clamp(self.zooms[1] if max_zoom is None else max_zoom)
+        while z > self.zooms[0] and (
+            (max(lons) - min(lons)) / 360 * (TILE << z) > self.width - 2 * margin
+            or (max(ys) - min(ys)) * (TILE << z) > self.height - 2 * margin
+        ):
+            z -= 1
+        self.set_view(((unmercator((max(ys) + min(ys)) / 2)), (max(lons) + min(lons)) / 2), z)
+
+    # ---------------------------------------------------------- loading
+
+    @property
+    def loading(self):
+        """True while strips of the map are still to be read."""
+        return bool(self._todo)
+
+    def _tile_file(self, x, y):
+        key = (x, y)
+        if key not in self._files:
+            self._files[key] = self.cache.open(self._zoom, x, y)
+        return self._files[key]
+
+    def _close_files(self):
+        for f in self._files.values():
+            if f:
+                f.close()
+        self._files = {}
+
+    def load_step(self):
+        """Read the next strip of the map into the underlay. Returns the
+        rectangle loaded, ``(x1, y1, x2, y2)`` (to redraw), or None when
+        the map is loaded."""
+        if not self._todo:
+            self._close_files()
+            return None
+        y1 = self._todo.pop(0) * self.strip
+        y2 = min(self.height, y1 + self.strip)
+        w = self.width
+        if self._centre is None:
+            bitmaptools.fill_region(self.under, 0, y1, w, y2, WAITING)
+            return (0, y1, w, y2)
+        n = 1 << self._zoom
+        y = y1
+        while y < y2:
+            # Rows y .. y + h are in the same row of tiles.
+            gy = self.y0 + y
+            ty = gy >> 8
+            h = min(y2 - y, TILE - (gy & 255))
+            sx = 0
+            while sx < w:
+                gx = self.x0 + sx
+                off = gx & 255
+                m = min(TILE - off, w - sx)
+                f = self._tile_file((gx >> 8) % n, ty) if 0 <= ty < n else None
+                if f is None:
+                    bitmaptools.fill_region(self.under, sx, y, sx + m, y + h, NO_TILE)
+                else:
+                    f.seek(BMP_HEADER + (gy & 255) * TILE)
+                    f.readinto(self._rows_mv[: h * TILE])
+                    bitmaptools.blit(self.under, self._rows, sx, y, x1=off, y1=0, x2=off + m, y2=h)
+                sx += m
+            y += h
+        return (0, y1, w, y2)
+
+    def load(self):
+        """Read every strip still to load. True if there were any."""
+        if not self._todo:
+            return False
+        while self.load_step():
+            pass
+        return True
+
+    # ---------------------------------------------------------- fetching
+
+    def fetch_step(self):
+        """Download (if needed) and convert the next missing tile: seconds.
+        Returns False if no tile was waiting. A download that fails sets
+        :attr:`net_error` and drops the tiles that need downloading (the
+        rest still convert); setting the view again retries them. A tile
+        fetched for the current view is queued to load."""
+        if not self.missing:
+            return False
+        z, x, y = self.missing.pop(0)
+        fetch = not self.cache.has_png(z, x, y)
+        try:
+            self.cache.get(z, x, y)
+        except Exception as error:
+            print("TILE_ERROR", z, x, y, type(error).__name__, error)
+            if fetch:
+                self.net_error = f"{type(error).__name__} {error}"
+                self.missing = [t for t in self.missing if self.cache.has_png(*t)]
+            return True
+        if z == self._zoom and self._centre is not None:
+            f = self._files.pop((x, y), None)
+            if f:
+                f.close()
+            # Reload the strips the tile is in.
+            top = (y << 8) - self.y0
+            for k in range(
+                max(0, top // self.strip), min(self.height, top + TILE) // self.strip + 1
+            ):
+                if k * self.strip < self.height and k not in self._todo:
+                    self._todo.append(k)
+        return True
+
+    def update(self, progress=None):
+        """Fetch every missing tile, then load the map: for programs that can
+        wait (seconds a tile). progress(done, total) is called before each
+        tile."""
+        total = len(self.missing)
+        while self.missing:
+            if progress:
+                progress(total - len(self.missing), total)
+            self.fetch_step()
+        self.load()
+
+    # ---------------------------------------------------------- drawing
+
+    def _clip(self, clip):
+        if clip is None:
+            return (0, 0, self.width, self.height)
+        return (
+            max(0, clip[0]),
+            max(0, clip[1]),
+            min(self.width, clip[2]),
+            min(self.height, clip[3]),
+        )
+
+    def restore(self, clip=None):
+        """Copy the tiles back over the map, in clip ``(x1, y1, x2, y2)``
+        (default: all of it), wiping what was drawn there."""
+        x1, y1, x2, y2 = self._clip(clip)
+        if x1 < x2 and y1 < y2:
+            bitmaptools.blit(self.bitmap, self.under, x1, y1, x1=x1, y1=y1, x2=x2, y2=y2)
+
+    def fill(self, x1, y1, x2, y2, colour, clip=None):  # noqa: PLR0913, PLR0917
+        """A filled rectangle, x2 and y2 exclusive."""
+        c = self._clip(clip)
+        x1, y1, x2, y2 = max(x1, c[0]), max(y1, c[1]), min(x2, c[2]), min(y2, c[3])
+        if x1 < x2 and y1 < y2:
+            bitmaptools.fill_region(self.bitmap, x1, y1, x2, y2, colour)
+
+    def line(self, x1, y1, x2, y2, colour, clip=None):  # noqa: PLR0913, PLR0917
+        """A line, clipped (Liang-Barsky)."""
+        c = self._clip(clip)
+        dx, dy = x2 - x1, y2 - y1
+        t0, t1 = 0, 1
+        for p, q in ((-dx, x1 - c[0]), (dx, c[2] - 1 - x1), (-dy, y1 - c[1]), (dy, c[3] - 1 - y1)):
+            if p == 0:
+                if q < 0:
+                    return
+            elif p < 0:
+                t0 = max(t0, q / p)
+            else:
+                t1 = min(t1, q / p)
+        if t0 <= t1:
+            bitmaptools.draw_line(
+                self.bitmap,
+                round(x1 + t0 * dx),
+                round(y1 + t0 * dy),
+                round(x1 + t1 * dx),
+                round(y1 + t1 * dy),
+                colour,
+            )
+
+    def blit(self, src, x, y, clip=None):
+        """The bitmap src (256 colours, RGB332) with its top left at x, y."""
+        c = self._clip(clip)
+        x1, y1 = max(x, c[0]), max(y, c[1])
+        x2, y2 = min(x + src.width, c[2]), min(y + src.height, c[3])
+        if x1 < x2 and y1 < y2:
+            bitmaptools.blit(self.bitmap, src, x1, y1, x1=x1 - x, y1=y1 - y, x2=x2 - x, y2=y2 - y)
+
+    def cross(self, x, y, clip=None):
+        """A white cross with a black middle, 13 pixels across, centred on
+        x, y (e.g. home)."""
+        self.fill(x - 6, y - 2, x + 7, y + 3, WHITE, clip)
+        self.fill(x - 2, y - 6, x + 3, y + 7, WHITE, clip)
+        self.fill(x - 5, y - 1, x + 6, y + 2, BLACK, clip)
+        self.fill(x - 1, y - 5, x + 2, y + 6, BLACK, clip)
+
+    def draw_legend(self, clip=None):
+        """The scale bar (bottom left) and the credit (bottom right)."""
+        if self.scale_bar is not None:
+            self.blit(self.scale_bar, 0, self.height - self.scale_bar.height, clip)
+        if self.credit is not None and self._centre is not None:
+            self.blit(
+                self.credit,
+                self.width - self.credit.width,
+                self.height - self.credit.height,
+                clip,
+            )
+
+    def dirty(self, clip=None):
+        """Mark the map (or clip of it) changed, for the next display refresh."""
+        if clip is None:
+            self.bitmap.dirty()
+        else:
+            x1, y1, x2, y2 = self._clip(clip)
+            if x1 < x2 and y1 < y2:
+                self.bitmap.dirty(x1, y1, x2, y2)
+
+    def redraw(self):
+        """The tiles and the legend, nothing else (a plain map): loads what
+        is still to load, then draws."""
+        self.load()
+        self.restore()
+        self.draw_legend()
+        self.dirty()
+
+    def close(self):
+        """Close any tile files left open by a partly loaded map."""
+        self._close_files()

adafruit_maptiles/png.py

@@ -0,0 +1,156 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tim Cocks for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`adafruit_maptiles.png`
+================================================================================
+
+PNG -> 8-bit BMP conversion, in the RGB332 colours that a CircuitPython
+8-bit framebuffer (e.g. ``picodvi`` with ``color_depth=8``) shows
+directly. The BMP's rows are top-down and, for a 256 pixel wide tile, need
+no padding, so a row of the tile is at ``BMP_HEADER + row * 256`` in the
+file and can be read straight into a :class:`displayio.Bitmap`.
+
+Converting a 256x256 tile takes ~1.5 s on an RP2350 (zlib, then a palette
+lookup per pixel in Python), so it is done once per tile and the BMP kept.
+
+Plain Python: it runs on a PC too (the tests do).
+"""
+
+import struct
+import zlib
+
+from adafruit_maptiles import rgb332, rgb332_colour
+
+BMP_HEADER = 14 + 40 + 1024
+"""Bytes before the pixels: file header, BITMAPINFOHEADER, 256-colour palette."""
+
+
+def bmp_header(width, height):
+    """8-bit top-down BMP header with the RGB332 palette."""
+    h = bytearray(BMP_HEADER)
+    stride = (width + 3) & ~3
+    struct.pack_into("<2sIHHI", h, 0, b"BM", BMP_HEADER + stride * height, 0, 0, BMP_HEADER)
+    struct.pack_into(
+        "<IiiHHIIiiII", h, 14, 40, width, -height, 1, 8, 0, stride * height, 2835, 2835, 256, 0
+    )
+    for v in range(256):
+        c = rgb332_colour(v)
+        struct.pack_into("<BBBB", h, 54 + 4 * v, c & 255, c >> 8 & 255, c >> 16, 0)
+    return h
+
+
+def _unfilter(f, cur, prev, bpp):
+    """Undo one PNG row filter in place (prev: the row above, unfiltered)."""
+    n = len(cur)
+    if f == 1:
+        for i in range(bpp, n):
+            cur[i] = (cur[i] + cur[i - bpp]) & 255
+    elif f == 2:
+        for i in range(n):
+            cur[i] = (cur[i] + prev[i]) & 255
+    elif f == 3:
+        for i in range(n):
+            a = cur[i - bpp] if i >= bpp else 0
+            cur[i] = (cur[i] + ((a + prev[i]) >> 1)) & 255
+    elif f == 4:
+        for i in range(n):
+            a = cur[i - bpp] if i >= bpp else 0
+            c = prev[i - bpp] if i >= bpp else 0
+            b = prev[i]
+            p = a + b - c
+            pa = abs(p - a)
+            pb = abs(p - b)
+            pc = abs(p - c)
+            cur[i] = (cur[i] + (a if pa <= pb and pa <= pc else b if pb <= pc else c)) & 255
+    elif f:
+        raise ValueError(f"PNG filter {f}")
+
+
+def png_to_bmp(data, out):  # noqa: PLR0912, PLR0914, PLR0915
+    """A PNG (bytes) -> an RGB332 BMP written to the open file out.
+    Indexed (1-8 bit), grey (1-8 bit) and 8-bit RGB, RGBA and grey+alpha;
+    transparent pixels become white. Returns ``(width, height)``.
+
+    :raises ValueError: not a PNG this can read (interlaced, 16-bit)
+    """
+    if bytes(data[:8]) != b"\x89PNG\r\n\x1a\n":
+        raise ValueError("not a PNG")
+    mv = memoryview(data)
+    pos = 8
+    idat = bytearray()
+    plte = trns = None
+    width = 0
+    while pos + 8 <= len(data):
+        ln = int.from_bytes(bytes(mv[pos : pos + 4]), "big")
+        kind = bytes(mv[pos + 4 : pos + 8])
+        body = mv[pos + 8 : pos + 8 + ln]
+        if kind == b"IHDR":
+            width, height, depth, ctype, _, _, interlace = struct.unpack(">IIBBBBB", bytes(body))
+        elif kind == b"PLTE":
+            plte = bytes(body)
+        elif kind == b"tRNS":
+            trns = bytes(body)
+        elif kind == b"IDAT":
+            idat.extend(body)
+        elif kind == b"IEND":
+            break
+        pos += 12 + ln
+    if not width:
+        raise ValueError("no IHDR")
+    channels = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}.get(ctype)
+    if channels is None or interlace or depth > 8 or (depth < 8 and ctype not in {0, 3}):
+        raise ValueError(f"PNG type {ctype} depth {depth} interlace {interlace}")
+    raw = zlib.decompress(idat)
+    del idat
+    stride = (width * channels * depth + 7) // 8
+    if len(raw) < (stride + 1) * height:
+        raise ValueError("PNG data short")
+    bpp = max(1, channels * depth // 8)
+    # Indexed and grey: one lookup per pixel value.
+    lut = None
+    if ctype == 3:
+        lut = bytearray(b"\xff" * 256)
+        for i in range(min(256, len(plte or b"") // 3)):
+            if trns is None or i >= len(trns) or trns[i] >= 128:
+                lut[i] = rgb332(plte[3 * i], plte[3 * i + 1], plte[3 * i + 2])
+    elif ctype == 0:
+        levels = (1 << depth) - 1
+        lut = bytearray(256)
+        for i in range(levels + 1):
+            v = i * 255 // levels
+            lut[i] = rgb332(v, v, v)
+    pad = (width + 3) & ~3
+    row = bytearray(pad)
+    prev = bytearray(stride)
+    out.write(bmp_header(width, height))
+    per_byte = 8 // depth
+    mask = (1 << depth) - 1
+    for y in range(height):
+        at = y * (stride + 1)
+        f = raw[at]
+        cur = bytearray(raw[at + 1 : at + 1 + stride])
+        if f:
+            _unfilter(f, cur, prev, bpp)
+        if lut is not None and depth == 8:
+            for x in range(width):
+                row[x] = lut[cur[x]]
+        elif lut is not None:
+            for x in range(width):
+                shift = 8 - depth * (x % per_byte + 1)
+                row[x] = lut[cur[x // per_byte] >> shift & mask]
+        elif ctype == 2:
+            for x in range(width):
+                k = 3 * x
+                row[x] = rgb332(cur[k], cur[k + 1], cur[k + 2])
+        elif ctype == 6:
+            for x in range(width):
+                k = 4 * x
+                row[x] = rgb332(cur[k], cur[k + 1], cur[k + 2]) if cur[k + 3] >= 128 else 0xFF
+        else:  # grey + alpha
+            for x in range(width):
+                v = cur[2 * x]
+                row[x] = rgb332(v, v, v) if cur[2 * x + 1] >= 128 else 0xFF
+        out.write(row)
+        prev = cur
+    return width, height