terraink-py 0.6.1

Standalone Python CLI for generating styled OSM map posters as PNG and SVG.

The repo is python version of terraink

中文文档 now also ships a standalone Python renderer that skips the website entirely and writes map posters directly to png and svg.

Installation

Install from PyPI:

pip install terraink_py

Or with uv (recommended for CLI tools):

uv tool install terraink_py

Usage

Generate a poster from a place name:

terraink \
  "Ganjingzi District, China" \
  --theme midnight_blue \
  --layout print_a4_portrait \
  --language en \
  --distance-m 4000 \
  --format png svg \
  --output outputs/ganjingzi

--location "..." still works; the positional argument is just a shorter alias.

To overlay routes from a running_page parquet, pass the repo slug or parquet URL:

terraink "Dalian" --running_page yihong0618/run --output outputs/dalian-run

When --running_page is set, the default --distance-m becomes 12000 unless you override it explicitly.

Development

Use uv in this repo:

uv sync --all-groups

Run the shared checks with prek:

uv run prek run --all-files

Then run via:

uv run terraink --help

Generate from coordinates in Python code:

from pathlib import Path

from terraink_py import PosterRequest, generate_poster

result = generate_poster(
    PosterRequest(
        output=Path("outputs/ganjingzi"),
        formats=("png", "svg"),
        lat=38.862405,
        lon=121.513525,
        title="Ganjingzi District",
        subtitle="China",
        theme="midnight_blue",
        width_cm=21,
        height_cm=29.7,
        distance_m=4000,
        include_buildings=True,
    )
)

print(result.files)

Notes:

• The Python renderer uses Nominatim + Overpass directly, so it is designed for city and regional posters rather than world-scale exports.
• svg output is true vector geometry, not a browser screenshot wrapped in SVG.
• Place label language defaults to auto-detect from your title/subtitle/query. Use --language en or --language zh to override it.
• Chinese place names now auto-fallback to common CJK system fonts on macOS/Linux; if your machine still lacks glyph coverage, pass --font-file /path/to/font.ttf.
• The PyPI package name is terraink_py, while the CLI command is terraink.