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:
1 parent
a03dedb09c
commit
d652a4e012
14 files changed
+2233
-7
No files matched your search
@@ -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.
|
||||
|
||||
|
||||
@@ -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)
|
||||
@@ -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,
|
||||
)
|
||||
|
||||
|
||||
|
||||
@@ -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
|
||||
Reference in new issue
Block a user