mapscii-py 0.1.0

A Python port of MapSCII's vector-tile terminal renderer

mapscii-py

A Python port of 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

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:

mapscii

Arrow keys or hjkl move the map, a zooms in, z zooms out, and q exits. Render one non-interactive frame with:

mapscii --once --width 80 --height 24

The module entry point is equivalent:

python3 -m mapscii_py --once

Rich integration

MapView adapts its width to the surrounding Rich layout and keeps a fixed number of terminal rows:

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:

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:

python3 -m pip install build twine
python3 -m build
python3 -m twine check dist/*

Upload a release to PyPI:

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.