terraink-py 0.1.0__tar.gz

terraink_py-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: terraink_py
+Version: 0.1.0
+Summary: Standalone Python CLI for generating styled OSM map posters as PNG and SVG.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=10.4.0
+
+## Python CLI
+
+The repo now also ships a standalone Python renderer that skips the website entirely and writes map posters directly to `png` and `svg`.
+
+Use `uv` in this repo:
+
+```bash
+uv sync
+```
+
+Generate a poster from a place name:
+
+```bash
+uv run terraink \
+  "Ganjingzi District, China" \
+  --theme midnight_blue \
+  --layout print_a4_portrait \
+  --distance-m 4000 \
+  --format png svg \
+  --output outputs/ganjingzi
+```
+
+`--location "..."` still works; the positional argument is just a shorter alias.
+
+If you want the CLI installed globally after publishing:
+
+```bash
+uv tool install terraink_py
+terraink --help
+```
+
+Build and publish to PyPI:
+
+```bash
+uv build
+uv publish
+```
+
+Generate from coordinates in Python code:
+
+```python
+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.
+- 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`.
+- PNG export needs `Pillow`; `uv sync` will install it automatically.
+- The PyPI package name is `terraink_py`, while the CLI command is `terraink`.
+

terraink_py-0.1.0/README.md

@@ -0,0 +1,72 @@
+## Python CLI
+
+The repo now also ships a standalone Python renderer that skips the website entirely and writes map posters directly to `png` and `svg`.
+
+Use `uv` in this repo:
+
+```bash
+uv sync
+```
+
+Generate a poster from a place name:
+
+```bash
+uv run terraink \
+  "Ganjingzi District, China" \
+  --theme midnight_blue \
+  --layout print_a4_portrait \
+  --distance-m 4000 \
+  --format png svg \
+  --output outputs/ganjingzi
+```
+
+`--location "..."` still works; the positional argument is just a shorter alias.
+
+If you want the CLI installed globally after publishing:
+
+```bash
+uv tool install terraink_py
+terraink --help
+```
+
+Build and publish to PyPI:
+
+```bash
+uv build
+uv publish
+```
+
+Generate from coordinates in Python code:
+
+```python
+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.
+- 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`.
+- PNG export needs `Pillow`; `uv sync` will install it automatically.
+- The PyPI package name is `terraink_py`, while the CLI command is `terraink`.
+

terraink_py-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "terraink_py"
+version = "0.1.0"
+description = "Standalone Python CLI for generating styled OSM map posters as PNG and SVG."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "Pillow>=10.4.0",
+]
+
+[project.scripts]
+terraink = "terraink_py.cli:main"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+terraink_py = ["data/*.json"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["terraink_py*"]

terraink_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

terraink_py-0.1.0/src/terraink_py/__init__.py

@@ -0,0 +1,14 @@
+from .api import PosterGenerator, generate_poster
+from .data import get_layout, get_theme, load_layouts, load_themes
+from .models import PosterRequest, PosterResult
+
+__all__ = [
+    "PosterGenerator",
+    "PosterRequest",
+    "PosterResult",
+    "generate_poster",
+    "get_layout",
+    "get_theme",
+    "load_layouts",
+    "load_themes",
+]

terraink_py-0.1.0/src/terraink_py/__main__.py

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

terraink_py-0.1.0/src/terraink_py/api.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .data import get_layout, get_theme
+from .geo import CM_PER_INCH, MercatorProjector, compute_poster_and_fetch_bounds, resolve_canvas_size
+from .http import CachedHttpClient
+from .models import Coordinate, PosterRequest, PosterResult
+from .osm import fetch_osm_layers, resolve_location
+from .render import build_scene, render_png, render_svg
+
+
+class PosterGenerator:
+    def generate(self, request: PosterRequest) -> PosterResult:
+        prepared = prepare_request(request)
+        prepared.validate()
+
+        client = CachedHttpClient(
+            cache_dir=prepared.cache_dir,
+            user_agent=prepared.user_agent,
+            timeout_seconds=prepared.timeout_seconds,
+        )
+        location = resolve_location(prepared, client)
+        center = Coordinate(lat=location.lat, lon=location.lon)
+        size = resolve_canvas_size(
+            prepared.width_cm / CM_PER_INCH,
+            prepared.height_cm / CM_PER_INCH,
+            dpi=prepared.dpi,
+            max_pixels=prepared.max_pixels,
+            max_side=prepared.max_side,
+        )
+        bounds = compute_poster_and_fetch_bounds(
+            center=center,
+            distance_meters=prepared.distance_m,
+            aspect_ratio=prepared.width_cm / prepared.height_cm,
+        )
+        layers = fetch_osm_layers(bounds.fetch_bounds, prepared, client)
+        projector = MercatorProjector.from_bounds(bounds.poster_bounds, size.width, size.height)
+        theme = get_theme(prepared.theme)
+        scene = build_scene(
+            size=size,
+            center=center,
+            title=(prepared.title or location.city or location.label).strip(),
+            subtitle=(prepared.subtitle or location.country).strip(),
+            theme=theme,
+            layers=layers,
+            projector=projector,
+            request=prepared,
+        )
+        output_paths = resolve_output_paths(prepared.output, prepared.formats)
+        files: list[Path] = []
+        for fmt, path in output_paths.items():
+            if fmt == "png":
+                render_png(scene, path)
+            elif fmt == "svg":
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(render_svg(scene), encoding="utf-8")
+            files.append(path)
+        return PosterResult(
+            files=tuple(files),
+            location=location,
+            theme=theme,
+            size=size,
+            bounds=bounds,
+        )
+
+
+def prepare_request(request: PosterRequest) -> PosterRequest:
+    if request.layout:
+        layout = get_layout(request.layout)
+        request.width_cm = layout.width_cm
+        request.height_cm = layout.height_cm
+    return request
+
+
+def resolve_output_paths(output: Path, formats: tuple[str, ...]) -> dict[str, Path]:
+    output = Path(output)
+    if len(formats) == 1 and output.suffix.lower() == f".{formats[0]}":
+        return {formats[0]: output}
+
+    base = output.with_suffix("") if output.suffix else output
+    return {fmt: base.with_suffix(f".{fmt}") for fmt in formats}
+
+
+def generate_poster(request: PosterRequest) -> PosterResult:
+    return PosterGenerator().generate(request)

terraink_py-0.1.0/src/terraink_py/cli.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .api import generate_poster
+from .data import load_layouts, load_themes
+from .models import DEFAULT_OVERPASS_URL, PosterRequest
+
+
+def build_parser() -> argparse.ArgumentParser:
+    themes = ", ".join(load_themes().keys())
+    layouts = ", ".join(load_layouts().keys())
+    parser = argparse.ArgumentParser(
+        prog="terraink",
+        description="Generate styled OpenStreetMap posters as PNG and SVG.",
+    )
+    parser.add_argument(
+        "query",
+        nargs="?",
+        help="Optional positional location query, equivalent to --location.",
+    )
+    parser.add_argument("--output", required=True, help="Output file path or base path.")
+    parser.add_argument("--format", nargs="+", default=["png"], choices=["png", "svg"])
+    parser.add_argument("--location", help="Location query for Nominatim geocoding.")
+    parser.add_argument("--lat", type=float, help="Latitude.")
+    parser.add_argument("--lon", type=float, help="Longitude.")
+    parser.add_argument("--title", help="Override poster title.")
+    parser.add_argument("--subtitle", help="Override poster subtitle.")
+    parser.add_argument("--theme", default="midnight_blue", help=f"Theme id. Available: {themes}")
+    parser.add_argument("--layout", help=f"Layout id. Available: {layouts}")
+    parser.add_argument("--width-cm", type=float, default=21.0, help="Poster width in centimeters.")
+    parser.add_argument("--height-cm", type=float, default=29.7, help="Poster height in centimeters.")
+    parser.add_argument("--distance-m", type=float, default=4000.0, help="Half-width map distance in meters.")
+    parser.add_argument("--dpi", type=int, default=300, help="Raster export DPI for PNG sizing.")
+    parser.add_argument("--font-file", type=Path, help="Optional TTF/OTF file used for PNG text rendering.")
+    parser.add_argument("--font-family", help="Font family name written into SVG text nodes.")
+    parser.add_argument("--cache-dir", type=Path, default=Path(".terraink-cache"))
+    parser.add_argument("--overpass-url", default=DEFAULT_OVERPASS_URL)
+    parser.add_argument("--nominatim-url", default="https://nominatim.openstreetmap.org")
+    parser.add_argument("--user-agent", default="terraink/0.1")
+    parser.add_argument("--timeout", type=int, default=90)
+    parser.add_argument("--hide-text", action="store_true", help="Do not draw poster title/subtitle/coords.")
+    parser.add_argument("--hide-credits", action="store_true", help="Do not draw footer credits.")
+    parser.add_argument("--include-buildings", action=argparse.BooleanOptionalAction, default=False)
+    parser.add_argument("--include-water", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--include-parks", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--include-aeroway", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--include-rail", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--include-roads", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--include-road-path", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--include-road-minor-low", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--include-road-outline", action=argparse.BooleanOptionalAction, default=True)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    request = PosterRequest(
+        output=Path(args.output),
+        formats=tuple(args.format),
+        location=args.location or args.query,
+        lat=args.lat,
+        lon=args.lon,
+        title=args.title,
+        subtitle=args.subtitle,
+        width_cm=args.width_cm,
+        height_cm=args.height_cm,
+        distance_m=args.distance_m,
+        dpi=args.dpi,
+        theme=args.theme,
+        layout=args.layout,
+        font_file=args.font_file,
+        font_family=args.font_family,
+        show_poster_text=not args.hide_text,
+        include_credits=not args.hide_credits,
+        include_buildings=args.include_buildings,
+        include_water=args.include_water,
+        include_parks=args.include_parks,
+        include_aeroway=args.include_aeroway,
+        include_rail=args.include_rail,
+        include_roads=args.include_roads,
+        include_road_path=args.include_road_path,
+        include_road_minor_low=args.include_road_minor_low,
+        include_road_outline=args.include_road_outline,
+        cache_dir=args.cache_dir,
+        overpass_url=args.overpass_url,
+        nominatim_url=args.nominatim_url,
+        user_agent=args.user_agent,
+        timeout_seconds=args.timeout,
+    )
+    result = generate_poster(request)
+    for path in result.files:
+        print(path)
+    return 0