mapscii-py 0.1.0__tar.gz

mapscii_py-0.1.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2017 Michael Straßburger
+Copyright (c) 2019 The MapSCII authors
+Copyright (c) 2026 David Nemeth-Csoka HA7NCS
+
+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.

mapscii_py-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: mapscii-py
+Version: 0.1.0
+Summary: A Python port of MapSCII's vector-tile terminal renderer
+Author-email: Dávid Németh-Csóka <encse@csokavar.hu>
+License: MIT License
+        
+        Copyright (c) 2017 Michael Straßburger
+        Copyright (c) 2019 The MapSCII authors
+        Copyright (c) 2026 David Nemeth-Csoka HA7NCS
+        
+        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.
+        
+Project-URL: Source, https://github.com/encse/adbs-tui/tree/main/mapscii
+Project-URL: Issues, https://github.com/encse/adbs-tui/issues
+Keywords: mapscii,terminal,map,vector-tiles,rich
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Terminals
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mapbox-vector-tile<3,>=2.2
+Requires-Dist: rich<15,>=13
+Dynamic: license-file
+
+# mapscii-py
+
+A Python port of [MapSCII](https://github.com/rastapasta/mapscii) for rendering
+OpenStreetMap vector tiles in terminals. It provides both an interactive CLI
+and a Rich-compatible `MapView` renderable for embedding maps in terminal
+applications.
+
+## Installation
+
+```sh
+python3 -m pip install mapscii-py
+```
+
+The distribution name is `mapscii-py`; the Python import package is
+`mapscii_py`.
+
+## Command line
+
+Start the interactive map:
+
+```sh
+mapscii
+```
+
+Arrow keys or `hjkl` move the map, `a` zooms in, `z` zooms out, and `q` exits.
+Render one non-interactive frame with:
+
+```sh
+mapscii --once --width 80 --height 24
+```
+
+The module entry point is equivalent:
+
+```sh
+python3 -m mapscii_py --once
+```
+
+## Rich integration
+
+`MapView` adapts its width to the surrounding Rich layout and keeps a fixed
+number of terminal rows:
+
+```python
+from rich.console import Console
+
+from mapscii_py import MapView
+
+map_view = MapView(
+    latitude=47.4979,
+    longitude=19.0402,
+    zoom=8,
+    height=16,
+)
+
+Console().print(
+    map_view.panel(title="Budapest airspace")
+)
+```
+
+Markers can be overlaid without modifying the underlying map tiles:
+
+```python
+from mapscii_py import MapMarker
+
+map_view.set_markers([
+    MapMarker(
+        latitude=47.4979,
+        longitude=19.0402,
+        label="Budapest",
+        symbol="●",
+    ),
+])
+```
+
+## Development and publishing
+
+Build and validate both the source distribution and wheel:
+
+```sh
+python3 -m pip install build twine
+python3 -m build
+python3 -m twine check dist/*
+```
+
+Upload a release to PyPI:
+
+```sh
+python3 -m twine upload dist/*
+```
+
+Increase the version in `pyproject.toml` and `mapscii_py/__init__.py` before
+building a new release. PyPI does not allow an existing release file or
+version to be replaced.
+
+## Attribution and license
+
+This implementation is derived from MapSCII, originally created by Michael
+Straßburger and the MapSCII contributors. Map data is © OpenStreetMap
+contributors.
+
+The project is distributed under the MIT License; see `LICENSE`.

mapscii_py-0.1.0/README.md

@@ -0,0 +1,101 @@
+# mapscii-py
+
+A Python port of [MapSCII](https://github.com/rastapasta/mapscii) for rendering
+OpenStreetMap vector tiles in terminals. It provides both an interactive CLI
+and a Rich-compatible `MapView` renderable for embedding maps in terminal
+applications.
+
+## Installation
+
+```sh
+python3 -m pip install mapscii-py
+```
+
+The distribution name is `mapscii-py`; the Python import package is
+`mapscii_py`.
+
+## Command line
+
+Start the interactive map:
+
+```sh
+mapscii
+```
+
+Arrow keys or `hjkl` move the map, `a` zooms in, `z` zooms out, and `q` exits.
+Render one non-interactive frame with:
+
+```sh
+mapscii --once --width 80 --height 24
+```
+
+The module entry point is equivalent:
+
+```sh
+python3 -m mapscii_py --once
+```
+
+## Rich integration
+
+`MapView` adapts its width to the surrounding Rich layout and keeps a fixed
+number of terminal rows:
+
+```python
+from rich.console import Console
+
+from mapscii_py import MapView
+
+map_view = MapView(
+    latitude=47.4979,
+    longitude=19.0402,
+    zoom=8,
+    height=16,
+)
+
+Console().print(
+    map_view.panel(title="Budapest airspace")
+)
+```
+
+Markers can be overlaid without modifying the underlying map tiles:
+
+```python
+from mapscii_py import MapMarker
+
+map_view.set_markers([
+    MapMarker(
+        latitude=47.4979,
+        longitude=19.0402,
+        label="Budapest",
+        symbol="●",
+    ),
+])
+```
+
+## Development and publishing
+
+Build and validate both the source distribution and wheel:
+
+```sh
+python3 -m pip install build twine
+python3 -m build
+python3 -m twine check dist/*
+```
+
+Upload a release to PyPI:
+
+```sh
+python3 -m twine upload dist/*
+```
+
+Increase the version in `pyproject.toml` and `mapscii_py/__init__.py` before
+building a new release. PyPI does not allow an existing release file or
+version to be replaced.
+
+## Attribution and license
+
+This implementation is derived from MapSCII, originally created by Michael
+Straßburger and the MapSCII contributors. Map data is © OpenStreetMap
+contributors.
+
+The project is distributed under the MIT License; see `LICENSE`.

mapscii_py-0.1.0/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-0.1.0/mapscii_py/__main__.py

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

mapscii_py-0.1.0/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-0.1.0/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-0.1.0/mapscii_py/py.typed

@@ -0,0 +1 @@
+