Add an interactive braille OpenStreetMap map of mesh nodes

New `map` tool (menu + `meshtools map` CLI) that plots the mesh's
location-sharing nodes over a real OSM street basemap rendered as Unicode
braille — streets, rivers, water, and place names — the mapscii idea, but
able to plot our own nodes and live inside the TUI.

- core/mvt.py: dependency-free MVT/protobuf vector-tile decoder.
- core/geo.py: Web Mercator + a pannable/zoomable Viewport and tile math.
- services/basemap.py: OpenFreeMap vector tiles (free, no API key), resolved
  from the versioned TileJSON, disk-cached, offline-safe (stdlib urllib only).
- ui/mapcanvas.py: colored braille canvas (per-cell priority, line raster,
  polygon fill, collision-avoided labels), emits truecolor ANSI.
- ui/map_render.py: compositor — basemap styling + node markers with names.
- ui/map_screen.py: full-screen screen; wasd/arrows pan, =/- zoom, r reset,
  Esc/q exit; background tile loading. Offline falls back to nodes on a grid.
- tools/map.py: interactive in the menu, one-shot static render on the CLI.

Repeaters are prioritised over leaf nodes via advert type: threaded `node_type`
through Observation/HeardNode and the persistence layer (schema v4->v5, with an
idempotent migration adding observations.node_type). Added
TuiSession.base_body_size() so a full-screen screen can size itself to the frame.

Tests: tests/test_map.py (24) cover MVT decode against a real cached tile
fixture, projection, the canvas, the compositor, offline behavior, and the
interactive pan/zoom/reset logic. Full suite: 261 passing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 4.8 committed 2026-07-07 17:38:39 -04:00
1 parent a03dedb09c
commit d652a4e012
14 files changed
+2233 -7

No files matched your search

+25 -1
View File
@@ -22,7 +22,16 @@ from typing import Callable, Optional
from .channels import CHANNEL_SLOT_PROBE_CAP
from .events import MeshEvent
from .models import Ack, Contact, Hop, Message, Observation, TraceResult
from .models import (
NODE_TYPE_CHAT,
NODE_TYPE_REPEATER,
Ack,
Contact,
Hop,
Message,
Observation,
TraceResult,
)
#: Module logger; enable DEBUG on ``meshtools.core.connection`` to trace the message pump.
_log = logging.getLogger(__name__)
@@ -1265,10 +1274,14 @@ class MockDevice(Device):
``advert`` otherwise, carrying a location for the simulated repeaters.
"""
lat_lon = self._MOCK_LOCATIONS.get(contact.name)
# The two located nodes are the simulated repeaters (fixed infrastructure); the rest
# advertise as ordinary chat nodes, so the map has both classes to prioritise.
node_type = NODE_TYPE_REPEATER if contact.name in self._MOCK_LOCATIONS else NODE_TYPE_CHAT
return Observation(
node=contact.key_prefix or contact.public_key[:12],
name=contact.name,
kind="telemetry" if seq % 4 == 3 else "advert",
node_type=node_type,
snr=round(self._rng.gauss(6.0, 3.0), 1),
rssi=round(self._rng.gauss(-95.0, 8.0), 1),
lat=lat_lon[0] if lat_lon else None,
@@ -1428,6 +1441,7 @@ def observation_from_event(event, kind: str) -> Optional[Observation]: # noqa:
node=node,
name=payload.get("adv_name") or payload.get("name"),
kind=kind,
node_type=_as_int(payload.get("adv_type", payload.get("type"))),
snr=_as_float(payload.get("snr")),
rssi=_as_float(payload.get("rssi")),
lat=_as_float(lat) if lat else None,
@@ -1487,6 +1501,16 @@ def _as_float(value: object) -> Optional[float]:
return None
def _as_int(value: object) -> Optional[int]:
"""Best-effort int conversion, returning ``None`` on missing/garbage values."""
if value is None:
return None
try:
return int(value) # type: ignore[arg-type]
except (TypeError, ValueError):
return None
def _advert_time(last_advert: object) -> Optional[datetime]:
"""Convert a contact's ``last_advert`` Unix timestamp to a UTC datetime.
+281
View File
@@ -0,0 +1,281 @@
"""Pure geographic helpers for the terminal map: Web Mercator, tiles, and viewports.
This module is deliberately I/O-free and rendering-free so it can be unit-tested without a
radio, a terminal, or the network. It turns latitude/longitude into the Web Mercator "world
pixel" space that slippy-map vector tiles live in, models the on-screen :class:`Viewport`
(which braille dot maps to which coordinate), and measures great-circle distances.
The map renders one braille **dot** per Web Mercator pixel at the viewport's zoom, so a
viewport of ``dot_w`` × ``dot_h`` dots shows exactly that many mercator pixels — panning and
zooming are then just moving and scaling this window over the world. Braille sub-cells are
about square in a monospace font (2 dots wide, 4 tall, in a cell roughly twice as tall as
wide), so mercator pixels land on screen without obvious distortion.
"""
from __future__ import annotations
import math
from dataclasses import dataclass
#: Mean radius of the Earth in kilometres, used for haversine distances.
EARTH_RADIUS_KM = 6371.0088
#: Web Mercator tile edge in pixels at its own zoom — the slippy-map convention. The world
#: is ``TILE_PX * 2**zoom`` pixels square at a given zoom.
TILE_PX = 256
@dataclass(frozen=True, slots=True)
class BBox:
"""An axis-aligned latitude/longitude bounding box (decimal degrees)."""
min_lat: float
min_lon: float
max_lat: float
max_lon: float
@classmethod
def around(cls, points: list[tuple[float, float]]) -> "BBox":
"""Return the tightest box containing every ``(lat, lon)`` point.
Args:
points: One or more latitude/longitude pairs (must be non-empty).
Returns:
The enclosing bounding box.
Raises:
ValueError: If ``points`` is empty.
"""
if not points:
raise ValueError("cannot build a bounding box from no points")
lats = [lat for lat, _ in points]
lons = [lon for _, lon in points]
return cls(min(lats), min(lons), max(lats), max(lons))
@property
def center(self) -> tuple[float, float]:
"""The box's centre as a ``(lat, lon)`` pair."""
return ((self.min_lat + self.max_lat) / 2, (self.min_lon + self.max_lon) / 2)
def haversine_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
"""Return the great-circle distance between two points in kilometres.
Args:
lat1: First point's latitude (degrees).
lon1: First point's longitude (degrees).
lat2: Second point's latitude (degrees).
lon2: Second point's longitude (degrees).
Returns:
The distance along the Earth's surface in kilometres.
"""
p1, p2 = math.radians(lat1), math.radians(lat2)
dphi = math.radians(lat2 - lat1)
dlambda = math.radians(lon2 - lon1)
a = math.sin(dphi / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dlambda / 2) ** 2
return 2 * EARTH_RADIUS_KM * math.asin(math.sqrt(a))
def clamp_lat(lat: float) -> float:
"""Clamp latitude to the Web Mercator limit (~±85.051°) where the projection is finite."""
return max(-85.05112878, min(85.05112878, lat))
def lonlat_to_world(lat: float, lon: float, zoom: float) -> tuple[float, float]:
"""Project ``(lat, lon)`` to Web Mercator world pixels at ``zoom``.
Args:
lat: Latitude in degrees (clamped to the mercator limit).
lon: Longitude in degrees.
zoom: Zoom level (may be fractional).
Returns:
``(x, y)`` in world pixels, where the world spans ``TILE_PX * 2**zoom`` on each axis
and ``y`` grows southward (north is up / smaller ``y``).
"""
scale = TILE_PX * (2.0**zoom)
x = (lon + 180.0) / 360.0 * scale
s = math.sin(math.radians(clamp_lat(lat)))
y = (0.5 - math.log((1 + s) / (1 - s)) / (4 * math.pi)) * scale
return x, y
def world_to_lonlat(x: float, y: float, zoom: float) -> tuple[float, float]:
"""Invert :func:`lonlat_to_world`: world pixels at ``zoom`` back to ``(lat, lon)``.
Args:
x: World-pixel x.
y: World-pixel y.
zoom: The zoom the pixels were computed at.
Returns:
The ``(lat, lon)`` in degrees.
"""
scale = TILE_PX * (2.0**zoom)
lon = x / scale * 360.0 - 180.0
n = math.pi - 2 * math.pi * y / scale
lat = math.degrees(math.atan(math.sinh(n)))
return lat, lon
@dataclass(frozen=True, slots=True)
class Viewport:
"""The on-screen window over the world: what each braille dot maps to.
One dot equals one Web Mercator pixel at :attr:`zoom`, so the visible area is exactly
``dot_w`` × ``dot_h`` mercator pixels centred on ``(center_lat, center_lon)``. Panning and
zooming return new viewports; nothing here mutates.
Attributes:
center_lat: Latitude at the centre of the view.
center_lon: Longitude at the centre of the view.
zoom: Display zoom (integer here; may exceed the tile source's max, in which case
lower-zoom tiles are magnified — see :meth:`tiles` / :meth:`feature_to_dot`).
dot_w: Viewport width in braille dots.
dot_h: Viewport height in braille dots.
"""
center_lat: float
center_lon: float
zoom: int
dot_w: int
dot_h: int
@property
def origin_world(self) -> tuple[float, float]:
"""Top-left corner of the view in world pixels at :attr:`zoom`."""
cx, cy = lonlat_to_world(self.center_lat, self.center_lon, self.zoom)
return cx - self.dot_w / 2, cy - self.dot_h / 2
def lonlat_to_dot(self, lat: float, lon: float) -> tuple[float, float]:
"""Project a coordinate to a (possibly off-screen) dot position in the view."""
ox, oy = self.origin_world
wx, wy = lonlat_to_world(lat, lon, self.zoom)
return wx - ox, wy - oy
def tile_zoom(self, max_tile_zoom: int) -> int:
"""The tile zoom to fetch: the display zoom, capped at the source's max."""
return max(0, min(self.zoom, max_tile_zoom))
def tiles(self, max_tile_zoom: int) -> list[tuple[int, int, int]]:
"""Return the ``(z, x, y)`` tiles covering the view at the fetchable tile zoom.
When the display zoom exceeds ``max_tile_zoom`` the lower-zoom tiles that cover the
same ground are returned (the renderer magnifies them), so zooming in past the
source's limit still works.
Args:
max_tile_zoom: The highest zoom the tile source actually serves.
Returns:
Tile coordinates, clamped to the valid range, de-duplicated in row-major order.
"""
tz = self.tile_zoom(max_tile_zoom)
scale = 2.0 ** (self.zoom - tz) # display px per tile-zoom px
ox, oy = self.origin_world
n = 2**tz
# Visible rect in tile-zoom world pixels, then in tile indices.
tx0 = int((ox / scale) // TILE_PX)
tx1 = int(((ox + self.dot_w) / scale) // TILE_PX)
ty0 = int((oy / scale) // TILE_PX)
ty1 = int(((oy + self.dot_h) / scale) // TILE_PX)
out: list[tuple[int, int, int]] = []
for ty in range(ty0, ty1 + 1):
if not 0 <= ty < n:
continue
for tx in range(tx0, tx1 + 1):
out.append((tz, tx % n, ty)) # wrap x around the antimeridian
return out
def feature_to_dot(
self, tile_x: int, tile_y: int, tile_zoom: int, extent: int, lx: float, ly: float
) -> tuple[float, float]:
"""Project a tile-local point to a dot position in this viewport.
Args:
tile_x: The tile's x index at ``tile_zoom``.
tile_y: The tile's y index at ``tile_zoom``.
tile_zoom: The zoom the tile was fetched at.
extent: The tile's internal coordinate extent (e.g. 4096).
lx: Local x within the tile, ``0..extent``.
ly: Local y within the tile, ``0..extent``.
Returns:
The ``(x, y)`` dot position (may be outside the canvas; the caller clips).
"""
scale = 2.0 ** (self.zoom - tile_zoom)
wx = (tile_x + lx / extent) * TILE_PX * scale
wy = (tile_y + ly / extent) * TILE_PX * scale
ox, oy = self.origin_world
return wx - ox, wy - oy
def panned(self, frac_x: float, frac_y: float) -> "Viewport":
"""Return a viewport shifted by a fraction of its own width/height.
Args:
frac_x: Eastward shift as a fraction of the view width (negative = west).
frac_y: Southward shift as a fraction of the view height (negative = north).
Returns:
A new :class:`Viewport` at the shifted centre, same zoom and size.
"""
cx, cy = lonlat_to_world(self.center_lat, self.center_lon, self.zoom)
cx += frac_x * self.dot_w
cy += frac_y * self.dot_h
lat, lon = world_to_lonlat(cx, cy, self.zoom)
return Viewport(clamp_lat(lat), lon, self.zoom, self.dot_w, self.dot_h)
def zoomed(self, delta: int, *, min_zoom: int = 2, max_zoom: int = 19) -> "Viewport":
"""Return a viewport zoomed by ``delta`` levels about the same centre (clamped)."""
z = max(min_zoom, min(max_zoom, self.zoom + delta))
return Viewport(self.center_lat, self.center_lon, z, self.dot_w, self.dot_h)
def resized(self, dot_w: int, dot_h: int) -> "Viewport":
"""Return the same view centred as before but at a new canvas size."""
return Viewport(self.center_lat, self.center_lon, self.zoom, dot_w, dot_h)
@classmethod
def fit(
cls,
points: list[tuple[float, float]],
dot_w: int,
dot_h: int,
*,
pad: float = 0.18,
min_zoom: int = 2,
max_zoom: int = 16,
default_zoom: int = 14,
) -> "Viewport":
"""Build a viewport framing ``points`` — centred on them at the tightest fitting zoom.
Args:
points: Latitude/longitude pairs to frame (may be empty).
dot_w: Canvas width in dots.
dot_h: Canvas height in dots.
pad: Fraction of the canvas kept as margin around the points.
min_zoom: Lowest zoom to consider.
max_zoom: Highest zoom to consider.
default_zoom: Zoom used when the points don't constrain it (0 or 1 point).
Returns:
A :class:`Viewport` centred on the points at a zoom where they fit with margin.
Empty input centres on the world at ``min_zoom``.
"""
if not points:
return cls(0.0, 0.0, min_zoom, dot_w, dot_h)
box = BBox.around(points)
center_lat, center_lon = box.center
if len(points) == 1 or (box.min_lat == box.max_lat and box.min_lon == box.max_lon):
return cls(center_lat, center_lon, default_zoom, dot_w, dot_h)
avail_w = dot_w * (1 - pad)
avail_h = dot_h * (1 - pad)
chosen = min_zoom
for z in range(max_zoom, min_zoom - 1, -1):
x0, y0 = lonlat_to_world(box.max_lat, box.min_lon, z) # NW corner
x1, y1 = lonlat_to_world(box.min_lat, box.max_lon, z) # SE corner
if abs(x1 - x0) <= avail_w and abs(y1 - y0) <= avail_h:
chosen = z
break
return cls(center_lat, center_lon, chosen, dot_w, dot_h)
+29
View File
@@ -15,6 +15,22 @@ from typing import Optional
#: Label used for our own (local) device when framing a trace path's endpoints.
LOCAL_DEVICE_LABEL = "us"
# MeshCore advert types — the low nibble of an advert's flag byte — classify the kind of
# node an advert announces. Repeaters are fixed infrastructure and carry the mesh, so
# location-aware features (e.g. the map) prioritise them over ordinary leaf nodes.
NODE_TYPE_CHAT = 1
NODE_TYPE_REPEATER = 2
NODE_TYPE_ROOM = 3
NODE_TYPE_SENSOR = 4
#: Human-readable label for each advert type, for legends and summaries.
NODE_TYPE_LABELS = {
NODE_TYPE_CHAT: "node",
NODE_TYPE_REPEATER: "repeater",
NODE_TYPE_ROOM: "room",
NODE_TYPE_SENSOR: "sensor",
}
def utcnow() -> datetime:
"""Return a timezone-aware UTC timestamp.
@@ -54,6 +70,8 @@ class Observation:
node: Key prefix / hash identifying the transmitting node, if known.
name: Friendly name advertised by the node, if carried.
kind: Packet class, e.g. ``advert`` or ``telemetry``.
node_type: Advert type of the transmitting node (see the ``NODE_TYPE_*`` constants),
e.g. :data:`NODE_TYPE_REPEATER`; ``None`` when the packet did not carry it.
snr: Signal-to-noise ratio (dB) the companion measured, if reported.
rssi: Received signal strength (dBm), if reported.
lat: Advertised latitude (decimal degrees), when the node shares location.
@@ -65,6 +83,7 @@ class Observation:
node: Optional[str]
name: Optional[str] = None
kind: str = "advert"
node_type: Optional[int] = None
snr: Optional[float] = None
rssi: Optional[float] = None
lat: Optional[float] = None
@@ -277,6 +296,8 @@ class HeardNode:
last_seen: Timestamp of the most recent observation.
lat: Most recent advertised latitude, if the node shared one.
lon: Most recent advertised longitude, if the node shared one.
node_type: Most recent advert type seen for the node (see the ``NODE_TYPE_*``
constants), if any observation carried it.
"""
node: Optional[str]
@@ -288,12 +309,18 @@ class HeardNode:
last_seen: datetime
lat: Optional[float] = None
lon: Optional[float] = None
node_type: Optional[int] = None
@property
def has_location(self) -> bool:
"""Whether this node reported a usable latitude/longitude."""
return self.lat is not None and self.lon is not None
@property
def is_repeater(self) -> bool:
"""Whether this node advertised itself as a repeater."""
return self.node_type == NODE_TYPE_REPEATER
@classmethod
def from_observations(
cls, node: Optional[str], observations: list["Observation"]
@@ -315,6 +342,7 @@ class HeardNode:
(o for o in reversed(ordered) if o.lat is not None and o.lon is not None), None
)
name = next((o.name for o in reversed(ordered) if o.name), None)
node_type = next((o.node_type for o in reversed(ordered) if o.node_type is not None), None)
return cls(
node=node,
name=name,
@@ -325,6 +353,7 @@ class HeardNode:
last_seen=latest.observed_at,
lat=located.lat if located else None,
lon=located.lon if located else None,
node_type=node_type,
)
+278
View File
@@ -0,0 +1,278 @@
"""A tiny, dependency-free Mapbox Vector Tile (MVT) decoder.
Vector tiles are Protocol-Buffer messages (spec: github.com/mapbox/vector-tile-spec). Rather
than pull in a protobuf runtime and a geometry library, this decodes the small subset the map
needs by hand: the protobuf wire format (varints, length-delimited fields) and the MVT
geometry command encoding (MoveTo/LineTo/ClosePath with zig-zag deltas). It is pure and
offline — the network fetch lives in :mod:`meshtools.services.basemap`.
The result is a list of :class:`Layer`, each with decoded :class:`Feature` geometry in
*tile-local* integer coordinates (``0..extent``) and a resolved ``tags`` dict, ready to be
projected to the screen by :class:`meshtools.core.geo.Viewport`.
"""
from __future__ import annotations
import gzip
from dataclasses import dataclass, field
from typing import Any, Optional
# MVT geometry types (Feature.type).
GEOM_POINT = 1
GEOM_LINE = 2
GEOM_POLYGON = 3
# Geometry command ids (low 3 bits of a command integer).
_CMD_MOVE_TO = 1
_CMD_LINE_TO = 2
_CMD_CLOSE = 7
class _Reader:
"""A minimal protobuf wire-format reader over a byte buffer."""
__slots__ = ("b", "i")
def __init__(self, b: bytes) -> None:
self.b = b
self.i = 0
def eof(self) -> bool:
return self.i >= len(self.b)
def varint(self) -> int:
"""Read a base-128 varint."""
result = shift = 0
while True:
byte = self.b[self.i]
self.i += 1
result |= (byte & 0x7F) << shift
if not byte & 0x80:
return result
shift += 7
def tag(self) -> tuple[int, int]:
"""Read a field tag, returning ``(field_number, wire_type)``."""
key = self.varint()
return key >> 3, key & 0x7
def blob(self) -> bytes:
"""Read a length-delimited byte string."""
n = self.varint()
v = self.b[self.i : self.i + n]
self.i += n
return v
def skip(self, wire_type: int) -> None:
"""Skip a field of the given wire type."""
if wire_type == 0:
self.varint()
elif wire_type == 2:
self.blob()
elif wire_type == 5:
self.i += 4
elif wire_type == 1:
self.i += 8
else: # pragma: no cover - groups are obsolete and never appear in MVT
raise ValueError(f"unsupported wire type {wire_type}")
def _zigzag(n: int) -> int:
"""Decode a protobuf zig-zag encoded signed integer."""
return (n >> 1) ^ -(n & 1)
@dataclass(slots=True)
class Feature:
"""One decoded vector-tile feature.
Attributes:
geom_type: :data:`GEOM_POINT`, :data:`GEOM_LINE`, or :data:`GEOM_POLYGON`.
rings: The geometry as a list of parts, each a list of ``(x, y)`` integer points in
tile-local coordinates (``0..extent``). Points have one part holding every point;
lines/polygons have one part per line-string / ring.
tags: Resolved attribute dict (e.g. ``{"class": "primary", "name": "Rue X"}``).
"""
geom_type: int
rings: list[list[tuple[int, int]]]
tags: dict[str, Any]
def get(self, key: str, default: Any = None) -> Any:
"""Return a tag value, or ``default`` if absent."""
return self.tags.get(key, default)
@property
def name(self) -> Optional[str]:
"""The feature's display name, preferring the local ``name`` then latin fallbacks."""
for key in ("name", "name:latin", "name:en", "name_en", "name_int"):
val = self.tags.get(key)
if val:
return str(val)
return None
@dataclass(slots=True)
class Layer:
"""A named vector-tile layer and its decoded features.
Attributes:
name: Layer id (e.g. ``transportation``, ``water``, ``place``).
extent: The tile's internal coordinate extent (typically 4096).
features: The decoded features.
"""
name: str
extent: int
features: list[Feature] = field(default_factory=list)
def _decode_geometry(cmds: list[int]) -> list[list[tuple[int, int]]]:
"""Decode an MVT geometry command stream into a list of point rings."""
rings: list[list[tuple[int, int]]] = []
current: list[tuple[int, int]] = []
x = y = 0
i = 0
n = len(cmds)
while i < n:
command = cmds[i]
i += 1
cmd_id = command & 0x7
count = command >> 3
if cmd_id == _CMD_MOVE_TO:
for _ in range(count):
x += _zigzag(cmds[i])
y += _zigzag(cmds[i + 1])
i += 2
# Each MoveTo starts a new part (multipoint keeps them in one part below).
if current:
rings.append(current)
current = [(x, y)]
elif cmd_id == _CMD_LINE_TO:
for _ in range(count):
x += _zigzag(cmds[i])
y += _zigzag(cmds[i + 1])
i += 2
current.append((x, y))
elif cmd_id == _CMD_CLOSE:
if current:
current.append(current[0]) # close the ring back to its start
if current:
rings.append(current)
return rings
def _decode_value(buf: bytes) -> Any:
"""Decode an MVT attribute Value message into a Python scalar."""
r = _Reader(buf)
while not r.eof():
field_no, wire = r.tag()
if field_no == 1 and wire == 2:
return r.blob().decode("utf-8", "ignore") # string_value
if field_no == 2 and wire == 5: # float_value
import struct
v = struct.unpack("<f", r.b[r.i : r.i + 4])[0]
r.i += 4
return v
if field_no == 3 and wire == 1: # double_value
import struct
v = struct.unpack("<d", r.b[r.i : r.i + 8])[0]
r.i += 8
return v
if field_no in (4, 5) and wire == 0: # int_value / uint_value
return r.varint()
if field_no == 6 and wire == 0: # sint_value
return _zigzag(r.varint())
if field_no == 7 and wire == 0: # bool_value
return bool(r.varint())
r.skip(wire)
return None
def _packed_uints(buf: bytes) -> list[int]:
"""Decode a packed repeated uint32 field into a list of ints."""
r = _Reader(buf)
out: list[int] = []
while not r.eof():
out.append(r.varint())
return out
def _decode_feature(buf: bytes, keys: list[str], values: list[Any]) -> Optional[Feature]:
"""Decode a single Feature message, resolving its tags against the layer's key/value pools."""
r = _Reader(buf)
geom_type = 0
tag_ints: list[int] = []
geom_ints: list[int] = []
while not r.eof():
field_no, wire = r.tag()
if field_no == 2 and wire == 2:
tag_ints = _packed_uints(r.blob())
elif field_no == 3 and wire == 0:
geom_type = r.varint()
elif field_no == 4 and wire == 2:
geom_ints = _packed_uints(r.blob())
else:
r.skip(wire)
if not geom_ints:
return None
tags: dict[str, Any] = {}
for k, v in zip(tag_ints[0::2], tag_ints[1::2]):
if 0 <= k < len(keys) and 0 <= v < len(values):
tags[keys[k]] = values[v]
return Feature(geom_type=geom_type, rings=_decode_geometry(geom_ints), tags=tags)
def _decode_layer(buf: bytes) -> Layer:
"""Decode a single Layer message and all of its features."""
r = _Reader(buf)
name = ""
extent = 4096
keys: list[str] = []
values: list[Any] = []
feature_blobs: list[bytes] = []
while not r.eof():
field_no, wire = r.tag()
if field_no == 1 and wire == 2:
name = r.blob().decode("utf-8", "ignore")
elif field_no == 2 and wire == 2:
feature_blobs.append(r.blob())
elif field_no == 3 and wire == 2:
keys.append(r.blob().decode("utf-8", "ignore"))
elif field_no == 4 and wire == 2:
values.append(_decode_value(r.blob()))
elif field_no == 5 and wire == 0:
extent = r.varint()
else:
r.skip(wire)
layer = Layer(name=name, extent=extent)
for blob in feature_blobs:
feat = _decode_feature(blob, keys, values)
if feat is not None:
layer.features.append(feat)
return layer
def decode_tile(data: bytes) -> list[Layer]:
"""Decode a vector tile (optionally gzip-compressed) into its layers.
Args:
data: Raw ``.pbf`` bytes, gzip-compressed or not.
Returns:
The decoded layers, in the order they appear in the tile. An empty or unparseable
tile yields an empty list rather than raising.
"""
if data[:2] == b"\x1f\x8b":
data = gzip.decompress(data)
r = _Reader(data)
layers: list[Layer] = []
while not r.eof():
field_no, wire = r.tag()
if field_no == 3 and wire == 2: # Tile.layers
layers.append(_decode_layer(r.blob()))
else:
r.skip(wire)
return layers