mapscii-py 0.1.0__py3-none-any.whl

mapscii_py/__init__.py

@@ -0,0 +1,15 @@
+"""A small Python port of MapSCII's vector-tile renderer."""
+
+__version__ = "0.1.0"
+
+from .renderer import Renderer
+from .rich_map import MapMarker, MapView
+from .tiles import HttpTileSource
+
+__all__ = [
+    "HttpTileSource",
+    "MapMarker",
+    "MapView",
+    "Renderer",
+    "__version__",
+]

mapscii_py/__main__.py

@@ -0,0 +1,6 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()
+

mapscii_py/canvas.py

@@ -0,0 +1,179 @@
+import math
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+
+BRAILLE_BITS = (
+    (0x01, 0x08),
+    (0x02, 0x10),
+    (0x04, 0x20),
+    (0x40, 0x80),
+)
+RESET = "\x1b[39;49m"
+
+
+class BrailleBuffer:
+    def __init__(self, width: int, height: int, use_braille: bool = True) -> None:
+        self.width = max(2, width - width % 2)
+        self.height = max(4, height - height % 4)
+        self.columns = self.width // 2
+        self.rows = self.height // 4
+        self.use_braille = use_braille
+        self.global_background: Optional[int] = None
+        self.clear()
+
+    def clear(self) -> None:
+        size = self.columns * self.rows
+        self.pixels = bytearray(size)
+        self.characters: List[Optional[str]] = [None] * size
+        self.foreground: List[Optional[int]] = [None] * size
+        self.background: List[Optional[int]] = [None] * size
+
+    def _index(self, x: int, y: int) -> int:
+        return x // 2 + self.columns * (y // 4)
+
+    def set_pixel(self, x: int, y: int, color: Optional[int]) -> None:
+        if not (0 <= x < self.width and 0 <= y < self.height):
+            return
+        index = self._index(x, y)
+        self.pixels[index] |= BRAILLE_BITS[y & 3][x & 1]
+        if color is not None:
+            self.foreground[index] = color
+
+    def set_character(self, character: str, x: int, y: int, color: Optional[int]) -> None:
+        if not (0 <= x < self.width and 0 <= y < self.height):
+            return
+        index = self._index(x, y)
+        self.characters[index] = character
+        if color is not None:
+            self.foreground[index] = color
+
+    def write_text(self, text: str, x: int, y: int, color: Optional[int], center: bool = False) -> None:
+        if center:
+            x -= len(text)
+        for offset, character in enumerate(text):
+            self.set_character(character, x + offset * 2, y, color)
+
+    def set_background(self, color: Optional[int]) -> None:
+        self.global_background = color
+
+    def _color_sequence(self, foreground: Optional[int], background: Optional[int]) -> str:
+        background = background if background is not None else self.global_background
+        if foreground is not None and background is not None:
+            return "\x1b[38;5;{};48;5;{}m".format(foreground, background)
+        if foreground is not None:
+            return "\x1b[49;38;5;{}m".format(foreground)
+        if background is not None:
+            return "\x1b[39;48;5;{}m".format(background)
+        return RESET
+
+    def frame(self) -> str:
+        output: List[str] = []
+        current_color: Optional[str] = None
+        for row in range(self.rows):
+            skip = 0
+            for column in range(self.columns):
+                index = row * self.columns + column
+                color = self._color_sequence(self.foreground[index], self.background[index])
+                if color != current_color:
+                    output.append(color)
+                    current_color = color
+
+                character = self.characters[index]
+                if character is not None:
+                    output.append(character)
+                    skip += max(0, len(character) - 1)
+                elif skip:
+                    skip -= 1
+                elif self.use_braille:
+                    output.append(chr(0x2800 + self.pixels[index]))
+                else:
+                    output.append(self._block_character(self.pixels[index]))
+            output.append(RESET + "\n")
+        return "".join(output)
+
+    @staticmethod
+    def _block_character(mask: int) -> str:
+        if mask == 0:
+            return " "
+        upper = mask & (0x01 | 0x02 | 0x08 | 0x10)
+        lower = mask & (0x04 | 0x40 | 0x20 | 0x80)
+        if upper and lower:
+            return "█"
+        if upper:
+            return "▀"
+        return "▄"
+
+
+class Canvas:
+    def __init__(self, width: int, height: int, use_braille: bool = True) -> None:
+        self.width = width
+        self.height = height
+        self.buffer = BrailleBuffer(width, height, use_braille)
+
+    def clear(self) -> None:
+        self.buffer.clear()
+
+    def frame(self) -> str:
+        return self.buffer.frame()
+
+    def set_background(self, color: Optional[int]) -> None:
+        self.buffer.set_background(color)
+
+    def text(self, text: str, x: int, y: int, color: Optional[int], center: bool = False) -> None:
+        self.buffer.write_text(text, x, y, color, center)
+
+    def polyline(self, points: Sequence[Tuple[int, int]], color: Optional[int], width: int = 1) -> None:
+        for start, end in zip(points, points[1:]):
+            self.line(start, end, color, width)
+
+    def line(self, start: Tuple[int, int], end: Tuple[int, int], color: Optional[int], width: int = 1) -> None:
+        x0, y0 = start
+        x1, y1 = end
+        radius = max(0, int(round(width)) - 1) // 2
+        for x, y in self._bresenham(x0, y0, x1, y1):
+            for dy in range(-radius, radius + 1):
+                for dx in range(-radius, radius + 1):
+                    self.buffer.set_pixel(x + dx, y + dy, color)
+
+    def polygon(self, rings: Sequence[Sequence[Tuple[int, int]]], color: Optional[int]) -> None:
+        edges = []
+        for ring in rings:
+            if len(ring) < 3:
+                continue
+            closed = list(ring)
+            if closed[0] != closed[-1]:
+                closed.append(closed[0])
+            edges.extend(zip(closed, closed[1:]))
+
+        for y in range(self.height):
+            intersections: List[float] = []
+            scan_y = y + 0.5
+            for (x1, y1), (x2, y2) in edges:
+                if y1 == y2:
+                    continue
+                if min(y1, y2) <= scan_y < max(y1, y2):
+                    intersections.append(x1 + (scan_y - y1) * (x2 - x1) / (y2 - y1))
+            intersections.sort()
+            for left, right in zip(intersections[0::2], intersections[1::2]):
+                for x in range(max(0, math.ceil(left)), min(self.width - 1, math.floor(right)) + 1):
+                    self.buffer.set_pixel(x, y, color)
+
+    @staticmethod
+    def _bresenham(x0: int, y0: int, x1: int, y1: int) -> Iterable[Tuple[int, int]]:
+        dx = abs(x1 - x0)
+        sx = 1 if x0 < x1 else -1
+        dy = -abs(y1 - y0)
+        sy = 1 if y0 < y1 else -1
+        error = dx + dy
+        while True:
+            yield x0, y0
+            if x0 == x1 and y0 == y1:
+                return
+            twice_error = 2 * error
+            if twice_error >= dy:
+                error += dy
+                x0 += sx
+            if twice_error <= dx:
+                error += dx
+                y0 += sy
+

mapscii_py/cli.py

@@ -0,0 +1,120 @@
+import argparse
+import math
+import os
+import select
+import shutil
+import sys
+import termios
+import tty
+from pathlib import Path
+from typing import Optional, Sequence, Tuple
+
+from .renderer import Renderer
+from .style import Styler
+from .tiles import HttpTileSource
+from .utils import base_zoom, lonlat_to_tile, normalize, tile_size_at_zoom, tile_to_lonlat
+
+
+DEFAULT_SOURCE = "http://mapscii.me/"
+DEFAULT_LATITUDE = 52.51298
+DEFAULT_LONGITUDE = 13.42012
+DEFAULT_STYLE = Path(__file__).resolve().parent / "styles" / "dark.json"
+
+
+def parse_arguments(argv: Optional[Sequence[str]] = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="MapSCII's vector-tile renderer ported to Python")
+    parser.add_argument("--latitude", "--lat", type=float, default=DEFAULT_LATITUDE)
+    parser.add_argument("--longitude", "--lon", type=float, default=DEFAULT_LONGITUDE)
+    parser.add_argument("--zoom", "-z", type=float)
+    parser.add_argument("--width", "-w", type=int, help="map width in terminal columns")
+    parser.add_argument("--height", type=int, help="map height in terminal rows")
+    parser.add_argument("--source", default=DEFAULT_SOURCE)
+    parser.add_argument("--style", type=Path, default=DEFAULT_STYLE)
+    parser.add_argument("--ascii", action="store_true", help="use block characters instead of Braille")
+    parser.add_argument("--no-cache", action="store_true")
+    parser.add_argument("--cache-directory", type=Path)
+    parser.add_argument("--once", action="store_true", help="render one frame and exit")
+    return parser.parse_args(argv)
+
+
+class Application:
+    def __init__(self, arguments: argparse.Namespace) -> None:
+        columns, rows = shutil.get_terminal_size((80, 24))
+        self.columns = arguments.width or columns
+        self.rows = arguments.height or max(2, rows - 1)
+        self.latitude = arguments.latitude
+        self.longitude = arguments.longitude
+        pixel_width = self.columns * 2
+        pixel_height = self.rows * 4
+        self.minimum_zoom = 4 - math.log2(4096 / pixel_width)
+        self.zoom = arguments.zoom if arguments.zoom is not None else self.minimum_zoom
+        self.zoom = max(self.minimum_zoom, min(18.0, self.zoom))
+
+        styler = Styler.from_file(arguments.style)
+        source = HttpTileSource(
+            arguments.source,
+            styler,
+            cache_directory=arguments.cache_directory,
+            persist=not arguments.no_cache,
+        )
+        self.renderer = Renderer(source, styler, pixel_width, pixel_height, not arguments.ascii)
+
+    def frame(self) -> str:
+        return self.renderer.draw(self.latitude, self.longitude, self.zoom)
+
+    def draw(self, clear: bool = True) -> None:
+        prefix = "\x1b[2J\x1b[H" if clear else ""
+        footer = "center: {:.3f}, {:.3f}  zoom: {:.2f}  arrows/hjkl move  a/z zoom  q quit  © OSM\n".format(
+            self.latitude, self.longitude, self.zoom
+        )
+        sys.stdout.write(prefix + self.frame() + "\x1b[0m" + footer)
+        sys.stdout.flush()
+
+    def move(self, dx: float, dy: float) -> None:
+        z = base_zoom(self.zoom)
+        center_x, center_y = lonlat_to_tile(self.longitude, self.latitude, z)
+        size = tile_size_at_zoom(self.zoom)
+        lon, lat = tile_to_lonlat(center_x + dx / size, center_y + dy / size, z)
+        self.longitude, self.latitude = normalize(lon, lat)
+
+    def run(self) -> None:
+        old_settings = termios.tcgetattr(sys.stdin.fileno())
+        try:
+            tty.setcbreak(sys.stdin.fileno())
+            self.draw()
+            while True:
+                key = os.read(sys.stdin.fileno(), 1)
+                if key == b"\x1b":
+                    while select.select([sys.stdin], [], [], 0.01)[0]:
+                        key += os.read(sys.stdin.fileno(), 1)
+                if key in (b"q", b"Q"):
+                    return
+                if key in (b"a",):
+                    self.zoom = min(18.0, self.zoom + 0.2)
+                elif key in (b"z", b"y"):
+                    self.zoom = max(self.minimum_zoom, self.zoom - 0.2)
+                elif key in (b"h", b"\x1b[D"):
+                    self.move(-16, 0)
+                elif key in (b"l", b"\x1b[C"):
+                    self.move(16, 0)
+                elif key in (b"k", b"\x1b[A"):
+                    self.move(0, -12)
+                elif key in (b"j", b"\x1b[B"):
+                    self.move(0, 12)
+                else:
+                    continue
+                self.draw()
+        finally:
+            termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, old_settings)
+            sys.stdout.write("\x1b[0m\n")
+
+
+def main(argv: Optional[Sequence[str]] = None) -> None:
+    arguments = parse_arguments(argv)
+    application = Application(arguments)
+    if arguments.once:
+        application.draw(clear=False)
+    else:
+        if not sys.stdin.isatty() or not sys.stdout.isatty():
+            raise SystemExit("interactive mode requires a TTY; use --once for redirected output")
+        application.run()

mapscii_py/py.typed

@@ -0,0 +1 @@
+

mapscii_py/renderer.py

@@ -0,0 +1,164 @@
+import math
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Set, Tuple
+
+from .canvas import Canvas
+from .style import Styler
+from .tiles import Feature, HttpTileSource, Tile
+from .utils import base_zoom, lonlat_to_tile, tile_size_at_zoom, xterm_color
+
+
+DRAW_ORDER_LOW = ("admin", "water", "country_label", "marine_label")
+DRAW_ORDER = (
+    "landuse", "water", "marine_label", "building", "road", "admin",
+    "country_label", "state_label", "water_label", "place_label",
+    "rail_station_label", "poi_label", "road_label", "housenum_label",
+)
+
+
+@dataclass
+class VisibleTile:
+    xyz: Tuple[int, int, int]
+    zoom: float
+    position: Tuple[float, float]
+    size: float
+    data: Optional[Tile] = None
+
+
+class LabelBuffer:
+    def __init__(self) -> None:
+        self.areas: List[Tuple[float, float, float, float]] = []
+
+    def clear(self) -> None:
+        self.areas.clear()
+
+    def reserve(self, text: str, x: int, y: int, margin: int = 5) -> bool:
+        column, row = x // 2, y // 4
+        area = (column - margin, row - margin / 2, column + len(text) + margin, row + margin / 2)
+        if any(self._intersects(area, existing) for existing in self.areas):
+            return False
+        self.areas.append(area)
+        return True
+
+    @staticmethod
+    def _intersects(left: Tuple[float, ...], right: Tuple[float, ...]) -> bool:
+        return not (left[2] < right[0] or left[0] > right[2] or left[3] < right[1] or left[1] > right[3])
+
+
+class Renderer:
+    def __init__(
+        self,
+        tile_source: HttpTileSource,
+        styler: Styler,
+        width: int,
+        height: int,
+        use_braille: bool = True,
+    ) -> None:
+        self.tile_source = tile_source
+        self.styler = styler
+        self.canvas = Canvas(width, height, use_braille)
+        self.width = self.canvas.buffer.width
+        self.height = self.canvas.buffer.height
+        self.labels = LabelBuffer()
+        self.seen_labels: Set[str] = set()
+
+    def draw(self, latitude: float, longitude: float, zoom: float) -> str:
+        self.canvas.clear()
+        self.labels.clear()
+        self.seen_labels.clear()
+        background = self.styler.background()
+        self.canvas.set_background(xterm_color(background) if background else None)
+
+        tiles = self.visible_tiles(latitude, longitude, zoom)
+        for tile in tiles:
+            tile.data = self.tile_source.get_tile(*tile.xyz)
+        self._render_tiles(tiles)
+        return self.canvas.frame()
+
+    def visible_tiles(self, latitude: float, longitude: float, zoom: float) -> List[VisibleTile]:
+        z = base_zoom(zoom)
+        center_x, center_y = lonlat_to_tile(longitude, latitude, z)
+        tile_size = tile_size_at_zoom(zoom)
+        radius_x = math.ceil(self.width / tile_size / 2) + 1
+        radius_y = math.ceil(self.height / tile_size / 2) + 1
+        grid_size = 2 ** z
+        visible: List[VisibleTile] = []
+
+        for raw_y in range(math.floor(center_y) - radius_y, math.floor(center_y) + radius_y + 1):
+            for raw_x in range(math.floor(center_x) - radius_x, math.floor(center_x) + radius_x + 1):
+                position_x = self.width / 2 - (center_x - raw_x) * tile_size
+                position_y = self.height / 2 - (center_y - raw_y) * tile_size
+                if raw_y < 0 or raw_y >= grid_size:
+                    continue
+                if position_x + tile_size < 0 or position_y + tile_size < 0:
+                    continue
+                if position_x > self.width or position_y > self.height:
+                    continue
+                visible.append(VisibleTile(
+                    xyz=(z, raw_x % grid_size, raw_y),
+                    zoom=zoom,
+                    position=(position_x, position_y),
+                    size=tile_size,
+                ))
+        return visible
+
+    def _render_tiles(self, tiles: Sequence[VisibleTile]) -> None:
+        draw_order = DRAW_ORDER_LOW if tiles and tiles[0].zoom < 2 else DRAW_ORDER
+        labels: List[Tuple[VisibleTile, Feature, int]] = []
+        for layer_name in draw_order:
+            for tile in tiles:
+                if tile.data is None or layer_name not in tile.data.layers:
+                    continue
+                extent, features = tile.data.layers[layer_name]
+                for feature in features:
+                    if feature.kind == "symbol":
+                        labels.append((tile, feature, extent))
+                    else:
+                        self._draw_feature(tile, feature, extent)
+
+        for tile, feature, extent in sorted(labels, key=lambda item: item[1].sort):
+            self._draw_feature(tile, feature, extent)
+
+    def _draw_feature(self, tile: VisibleTile, feature: Feature, extent: int) -> None:
+        if feature.min_zoom is not None and tile.zoom < feature.min_zoom:
+            return
+        if feature.max_zoom is not None and tile.zoom > feature.max_zoom:
+            return
+        scale = extent / tile.size
+
+        if feature.kind == "line":
+            points = self._scale_points(tile, feature.geometry, scale)
+            if len(points) >= 2:
+                self.canvas.polyline(points, feature.color, feature.width)
+        elif feature.kind == "fill":
+            rings = [self._scale_points(tile, ring, scale) for ring in feature.geometry]
+            self.canvas.polygon([ring for ring in rings if len(ring) >= 3], feature.color)
+        elif feature.kind == "symbol":
+            text = feature.label or "◉"
+            if text in self.seen_labels and feature.label:
+                return
+            for x, y in self._scale_points(tile, feature.geometry, scale):
+                start_x = x - len(text)
+                if self.labels.reserve(text, start_x, y):
+                    self.canvas.text(text, start_x, y, feature.color)
+                    self.seen_labels.add(text)
+                    return
+
+    def _scale_points(
+        self,
+        tile: VisibleTile,
+        points: Sequence[Tuple[float, float]],
+        scale: float,
+    ) -> List[Tuple[int, int]]:
+        output: List[Tuple[int, int]] = []
+        previous: Optional[Tuple[int, int]] = None
+        for source_x, source_y in points:
+            point = (
+                math.floor(tile.position[0] + source_x / scale),
+                math.floor(tile.position[1] + source_y / scale),
+            )
+            if point != previous:
+                output.append(point)
+                previous = point
+        return output
+