roadstyle 0.2.0__py3-none-any.whl

roadstyle/__init__.py

@@ -0,0 +1,124 @@
+"""roadstyle — OSM-style road/edge map styling; self-contained MapLibre maps (plus folium & lonboard).
+
+    import geopandas as gpd
+    from roadstyle import render_edges
+
+    edges = gpd.read_file(...)                       # needs a `highway` column
+    render_edges(edges).save("map.html")             # web backend, Voyager base (settings default)
+    render_edges(edges, basemap="dark_matter",
+                 include=["motorway", "trunk", "primary"]).save("major.html")
+"""
+from .basemaps import BASEMAPS, Basemap, get_basemap, register_basemap
+from .config import StyleConfig
+from .controls import BaseLayerSwitcher
+from .edges import (
+    RoadEdges,
+    as_edges,
+    from_arrow,
+    from_duckdb,
+    from_geojson,
+    load_edges,
+    normalize_edges,
+)
+from .emit import (
+    load_spec,
+    save,
+    save_spec,
+    to_geojson,
+    to_html,
+    to_iframe,
+    to_spec,
+)
+from .filters import filter_edges, highway_types
+from .legend import make_legend
+from .overlays import Overlay
+from .palettes import (
+    CARTO,
+    HIGHSAT,
+    PALETTES,
+    SELECTION,
+    RoadStyle,
+    load_palette,
+    palette_from_dict,
+    palette_to_dict,
+    register_palette,
+    save_palette,
+)
+from .render import render_edges
+from .snapshot import snapshot
+from .style import base_style, normalize_highway, resolve, selection_style
+from .stylers import (
+    CategoricalStyler,
+    ClassStyler,
+    ColorTableStyler,
+    NumericStyler,
+    ResolvedFrame,
+    Styler,
+    build_styler,
+    color_by,
+    color_by_class,
+    color_by_value,
+)
+
+
+def use_settings(*sources) -> None:
+    """Apply settings overrides from code — the in-process equivalent of a ``roadstyle.json``.
+
+    Each source is a path to a JSON file or a dict, in the same
+    ``{"palettes", "config", "selection", "roads"}`` layout as an override file (state only what
+    changes; everything else keeps the bundled defaults + any discovered override files, which
+    these sources outrank; later sources outrank earlier ones). Call with no arguments to drop
+    the programmatic overrides again. For a single render, prefer
+    ``render_edges(..., settings=...)`` — it applies and restores automatically.
+
+    Safe to call at any point before rendering — already-imported styling tables (palettes,
+    ``StyleConfig``, the web renderer's road model) are rebuilt in place::
+
+        import roadstyle as rs
+        rs.use_settings("styles/dark-flow.json")     # or a dict
+        rs.render_edges(edges, backend="web").save("map.html")
+
+    Two setting sets in one process = call it again between renders. Note the handful of legacy
+    class-level defaults (:class:`roadstyle.style.RoadStyle` field defaults) resolve at import and
+    are unaffected — palette entries always restate them, so rendering is unaffected too.
+    """
+    from . import _settings, config, palettes, render_web, style, stylers
+
+    _settings.set_extra(*sources)
+    config.DEFAULT = config._default_config()
+    style.DEFAULT = stylers.DEFAULT = render_web.CONFIG = config.DEFAULT
+    palettes._reload()
+    render_web._load_road_model()
+
+
+# Single source of truth is [project] version in pyproject.toml (read from the install metadata).
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("roadstyle")
+except Exception:                                    # running from a bare source tree
+    __version__ = "0+unknown"
+
+__all__ = [
+    "render_edges", "filter_edges", "highway_types", "use_settings", "snapshot",
+    "resolve", "base_style", "selection_style", "normalize_highway",
+    "PALETTES", "HIGHSAT", "CARTO", "SELECTION", "RoadStyle",
+    "BASEMAPS", "Basemap", "get_basemap", "BaseLayerSwitcher",
+    # generalization additions (Phase 0)
+    "StyleConfig", "register_palette", "register_basemap",
+    # styler abstraction (Phase 1)
+    "Styler", "ClassStyler", "ResolvedFrame",
+    # palette JSON I/O (Phase 2a)
+    "load_palette", "save_palette", "palette_to_dict", "palette_from_dict",
+    # data-driven styling (Phase 2)
+    "CategoricalStyler", "NumericStyler", "ColorTableStyler", "build_styler",
+    "color_by", "color_by_value", "color_by_class",
+    # canonical input (Phase 3a)
+    "RoadEdges", "normalize_edges", "load_edges", "as_edges",
+    "from_geojson", "from_arrow", "from_duckdb",
+    # legends (Phase 3)
+    "make_legend",
+    # extra overlay layers (zones / POIs / any geometry)
+    "Overlay",
+    # web / JSON output (Phase 4)
+    "to_spec", "to_geojson", "to_html", "to_iframe", "save", "save_spec", "load_spec",
+]

roadstyle/_settings.py

@@ -0,0 +1,182 @@
+"""Where roadstyle's built-in styling *data* lives, and how user overrides layer on top.
+
+EVERY styling setting ships in ONE bundled JSON file — ``roadstyle/data/defaults.json`` — with
+four sections (same layout as a user override file):
+
+    palettes   per-class colours/widths of each named palette (highsat / carto / mono)
+    config     the StyleConfig knobs (opacities, casing, minzoom, labels, arrows, ...)
+    selection  the click/hover highlight colours
+    roads      the web renderer's road model: ``width`` (px by zoom, per width-group),
+               ``width_zoom_rate``, ``casing_ratio``, ``group`` (class -> width-group),
+               ``links``, ``zoom_stops``, ``z_order`` (draw priority)
+
+This module is the single place that reads those bundled defaults and **merges user overrides**
+on top. A user of the library never edits the package — they create their own file restating
+only the parts they want changed. Override sources, lowest precedence first (later ones win)::
+
+    1. ``$XDG_CONFIG_HOME/roadstyle/roadstyle.json``  (or ``~/.config/roadstyle/roadstyle.json``)
+    2. ``./roadstyle.json``                            (project-local, current working dir)
+    3. ``$ROADSTYLE_CONFIG``                           (explicit file path)
+
+An override file is JSON of the form::
+
+    {
+      "palettes": {
+        "highsat": {"service": {"fill": "#EEEEEE"}},   # partial — merged per road class
+        "mytheme": {"roads": {...}}                      # new palette (full class entries)
+      },
+      "config":    {"fill_opacity": 0.95, "labels": {"color": "#8899aa"}},
+      "selection": {"core": "#FF0000"},
+      "roads":     {"z_order": {"service": 5}}           # partial — merged per table entry
+    }
+
+Palette overrides are **deep-merged per road class** and ``roads`` tables per entry, so one key
+can change without restating its table; ``config``/``selection`` overrides replace individual
+keys. This module imports nothing from roadstyle (it returns only plain dicts), so
+``palettes.py``, ``config.py`` and ``render_web.py`` can import it without a cycle.
+"""
+from __future__ import annotations
+
+import json
+import os
+from functools import lru_cache
+from pathlib import Path
+
+
+def _read_json(path: Path) -> dict:
+    with open(path, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+@lru_cache(maxsize=1)
+def data_dir() -> Path:
+    """Filesystem path to the bundled ``roadstyle/data`` directory (shipped as package data)."""
+    return Path(__file__).resolve().parent / "data"
+
+
+@lru_cache(maxsize=1)
+def _bundled() -> dict:
+    """The whole bundled default set — ``data/defaults.json`` (palettes/config/selection/roads)."""
+    return _read_json(data_dir() / "defaults.json")
+
+
+def _bundled_palettes() -> dict[str, dict]:
+    """``{palette_name: {class: roadstyle_dict}}`` from the bundled defaults."""
+    return _bundled().get("palettes", {})
+
+
+def _bundled_style() -> dict:
+    """``{"config": {...}, "selection": {...}}`` from the bundled defaults."""
+    return _bundled()
+
+
+def override_files() -> list[Path]:
+    """Existing user-override files, lowest precedence first (later ones win)."""
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    home_cfg = Path(xdg) if xdg else Path.home() / ".config"
+    candidates = [home_cfg / "roadstyle" / "roadstyle.json", Path.cwd() / "roadstyle.json"]
+    env = os.environ.get("ROADSTYLE_CONFIG")
+    if env:
+        candidates.append(Path(env))
+    return [p for p in candidates if p.is_file()]
+
+
+def _norm_roads(value):
+    """A palette-override value → its ``{class: {...}}`` mapping (accepts a ``roads`` wrapper)."""
+    return value.get("roads", value) if isinstance(value, dict) else value
+
+
+#: programmatic override sources set via :func:`roadstyle.use_settings` — paths or dicts,
+#: applied AFTER the discovered files (highest precedence)
+_EXTRA: list = []
+
+
+def set_extra(*sources) -> None:
+    """Replace the programmatic override sources (the :func:`roadstyle.use_settings` backing) and
+    drop caches so the next access sees them. ``None`` entries are ignored (reset with no args)."""
+    _EXTRA[:] = [s for s in sources if s is not None]
+    refresh()
+
+
+def _merged_overrides() -> dict:
+    """Merge every override source into one ``{"palettes", "config", "selection", "roads"}`` dict."""
+    merged: dict = {"palettes": {}, "config": {}, "selection": {}, "roads": {}}
+    for src in list(override_files()) + list(_EXTRA):
+        if isinstance(src, dict):
+            data = src
+        else:
+            try:
+                data = _read_json(Path(src))
+            except (OSError, ValueError):      # unreadable / malformed JSON → skip, don't crash
+                continue
+        for name, value in (data.get("palettes") or {}).items():
+            dst = merged["palettes"].setdefault(name, {})
+            for cls, fields in (_norm_roads(value) or {}).items():
+                dst.setdefault(cls, {}).update(fields)       # deep-merge per class
+        merged["config"].update(data.get("config") or {})
+        merged["selection"].update(data.get("selection") or {})
+        for table, value in (data.get("roads") or {}).items():
+            if isinstance(value, dict):                      # deep-merge per table entry
+                merged["roads"].setdefault(table, {}).update(value)
+            else:                                            # lists (links, zoom_stops): replace
+                merged["roads"][table] = value
+    return merged
+
+
+@lru_cache(maxsize=1)
+def palettes() -> dict[str, dict]:
+    """Bundled palettes with user overrides deep-merged per road class.
+
+    Returns ``{name: {class: roadstyle_dict}}`` — raw dicts, ready for ``palette_from_dict``.
+    """
+    out = {name: {cls: dict(fields) for cls, fields in roads.items()}
+           for name, roads in _bundled_palettes().items()}
+    for name, roads in _merged_overrides()["palettes"].items():
+        dst = out.setdefault(name, {})
+        for cls, fields in roads.items():
+            dst.setdefault(cls, {}).update(fields)
+    return out
+
+
+@lru_cache(maxsize=1)
+def style() -> dict:
+    """Bundled ``config`` / ``selection`` with user overrides applied per key."""
+    base = _bundled_style()
+    ov = _merged_overrides()
+    return {
+        "config": {**base.get("config", {}), **ov["config"]},
+        "selection": {**base.get("selection", {}), **ov["selection"]},
+    }
+
+
+@lru_cache(maxsize=1)
+def roads() -> dict:
+    """The web renderer's road model tables, with user overrides deep-merged per entry.
+
+    Keys: ``width`` (px by zoom, per width-group — zoom keys are strings in JSON, the consumer
+    coerces), ``width_zoom_rate``, ``casing_ratio``, ``group``, ``links``, ``zoom_stops``,
+    ``z_order``.
+    """
+    base = _bundled().get("roads", {})
+    out = {k: (dict(v) if isinstance(v, dict) else list(v)) for k, v in base.items()}
+    for table, value in _merged_overrides()["roads"].items():
+        if isinstance(value, dict) and isinstance(out.get(table), dict):
+            for k, v in value.items():                       # per-entry; width rows merge per zoom
+                if isinstance(v, dict) and isinstance(out[table].get(k), dict):
+                    out[table][k] = {**out[table][k], **v}
+                else:
+                    out[table][k] = v
+        else:
+            out[table] = value
+    return out
+
+
+def refresh() -> None:
+    """Drop cached data so the next access re-reads the files.
+
+    Call after editing an override file in-process (or from tests that point
+    ``$ROADSTYLE_CONFIG`` at a temp file). Note that ``palettes`` / ``config`` already imported
+    elsewhere keep their import-time values; ``render_edges(palette=...)`` re-reads ``PALETTES``.
+    """
+    for fn in (data_dir, _bundled, palettes, style, roads):
+        fn.cache_clear()

roadstyle/basemaps.py

@@ -0,0 +1,113 @@
+"""Base-map (tile) providers + thumbnail metadata for the switcher control."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_CARTO_ATTR = "© OpenStreetMap contributors © CARTO"
+_OSM_ATTR = "© OpenStreetMap contributors"
+_ESRI_ATTR = "Tiles © Esri"
+
+
+@dataclass(frozen=True)
+class Basemap:
+    key: str
+    label: str
+    url: str                       # leaflet tile URL template ({s}{z}{x}{y}{r})
+    attr: str
+    is_dark: bool = False          # dark canvas?
+    satellite: bool = False        # apply the saturate/brightness tile filter
+    lonboard: str | None = None    # CartoBasemap name (lonboard backend)
+    bg: str = "#444"               # thumbnail background (CSS)
+    preview: tuple[str, str, str] = ("#888", "#bbb", "#888")  # 3 preview road colours
+    subdomains: str = "abc"
+
+
+BASEMAPS: dict[str, Basemap] = {
+    "voyager": Basemap(
+        "voyager", "Voyager",
+        "https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png", _CARTO_ATTR,
+        lonboard="Voyager", bg="linear-gradient(180deg,#e8eef0,#d8e0e5)",
+        preview=("#ff9933", "#e8ecef", "#9ec5fe")),
+    "positron": Basemap(
+        "positron", "Positron",
+        "https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png", _CARTO_ATTR,
+        lonboard="Positron", bg="linear-gradient(180deg,#f3f5f7,#e3e8ed)",
+        preview=("#888", "#bbb", "#888")),
+    "dark_matter": Basemap(
+        "dark_matter", "Dark Matter",
+        "https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png", _CARTO_ATTR,
+        is_dark=True, lonboard="DarkMatter", bg="radial-gradient(circle,#18222e,#0b1014)",
+        preview=("#22d3a3", "#9ec5fe", "#5b6573")),
+    "osm": Basemap(
+        "osm", "OpenStreetMap",
+        "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", _OSM_ATTR,
+        bg="linear-gradient(180deg,#f2efe9,#e8e4db)", preview=("#e07020", "#dcdcdc", "#888")),
+    "esri_gray": Basemap(
+        "esri_gray", "Light Gray",
+        "https://server.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer/tile/{z}/{y}/{x}",
+        _ESRI_ATTR, bg="linear-gradient(180deg,#eceff1,#d8dde1)", preview=("#9aa", "#ccc", "#9aa")),
+    "satellite": Basemap(
+        "satellite", "Satellite",
+        "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}",
+        _ESRI_ATTR, is_dark=True, satellite=True,
+        bg="linear-gradient(140deg,#2d3823,#4a3a2a,#2a2820)",
+        preview=("#ffe8a0", "#ffd84d", "#fffdf2")),
+    # tile-less base maps: url="" means no tile layer at all — just a plain canvas colour (bg).
+    # Zero network requests, so a saved map with one of these is fully offline.
+    "blank": Basemap(
+        "blank", "Blank", "", "", bg="#efede8", preview=("#888", "#bbb", "#888")),
+    "blank_dark": Basemap(
+        "blank_dark", "Blank dark", "", "", is_dark=True, bg="#14181d",
+        preview=("#22d3a3", "#9ec5fe", "#5b6573")),
+}
+
+# default set offered by the switcher when the caller doesn't specify one
+DEFAULT_SWITCHER = ["voyager", "positron", "dark_matter", "osm", "satellite", "blank"]
+
+
+def register_basemap(bm: Basemap) -> None:
+    """Register (or replace) a base map, keyed by its ``key``."""
+    if not isinstance(bm, Basemap):
+        raise TypeError(f"expected a Basemap, got {type(bm).__name__}")
+    BASEMAPS[bm.key] = bm
+
+
+def _basemap_from_provider(tp) -> Basemap:
+    """Convert an ``xyzservices.TileProvider`` (duck-typed) into a :class:`Basemap`.
+
+    Lets any of the hundreds of xyzservices tile sources be used directly, e.g.
+    ``render_edges(edges, basemap=xyzservices.providers.CartoDB.Positron)``.
+    """
+    name = getattr(tp, "name", None) or (
+        tp.get("name", "custom") if hasattr(tp, "get") else "custom"
+    )
+    try:
+        url = tp.build_url()              # leaflet-style template with {z}/{x}/{y}
+    except Exception:
+        url = tp.get("url", "") if hasattr(tp, "get") else ""
+    attr = ""
+    if hasattr(tp, "get"):
+        attr = tp.get("attribution", "") or tp.get("html_attribution", "") or ""
+    is_dark = "dark" in str(name).lower()
+    return Basemap(key=str(name), label=str(name).replace("_", " "), url=url, attr=attr,
+                   is_dark=is_dark)
+
+
+def get_basemap(key: str | Basemap) -> Basemap:
+    """Resolve a base map from a registered key, a :class:`Basemap`, or an
+    ``xyzservices.TileProvider`` (duck-typed via its ``build_url`` method)."""
+    if isinstance(key, Basemap):
+        return key
+    if isinstance(key, str):
+        try:
+            return BASEMAPS[key]
+        except KeyError as err:
+            raise ValueError(
+                f"unknown basemap {key!r}; choose from {list(BASEMAPS)}"
+            ) from err
+    if hasattr(key, "build_url"):         # xyzservices.TileProvider
+        return _basemap_from_provider(key)
+    raise TypeError(
+        f"basemap must be a key, Basemap, or xyzservices.TileProvider, "
+        f"got {type(key).__name__}"
+    )

roadstyle/cli.py

@@ -0,0 +1,169 @@
+"""``roadstyle`` command-line interface — turn a road file into a styled map without writing Python.
+
+    roadstyle edges.gpkg -o map.html --basemap dark_matter
+    roadstyle edges.gpkg --color-by aadt --cmap viridis --width-by 1 6 -f web
+    roadstyle edges.gpkg --include motorway trunk primary -o major.html
+
+A thin wrapper over :func:`roadstyle.render_edges` (the ``web`` MapLibre backend — the default — and
+``folium``) and :func:`roadstyle.save` / :func:`roadstyle.save_spec` / :func:`roadstyle.to_geojson`
+(the ``rsjs`` roadstyle.js page / JSON outputs). Every styling flag mirrors the Python keyword of
+the same name, so the CLI and the library stay in lock-step.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+
+# output format → default file extension for the derived output name
+_EXT = {"web": ".html", "folium": ".html", "rsjs": ".html", "spec": ".json", "geojson": ".geojson"}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="roadstyle",
+        description="Render a road-edge file (GPKG, GeoJSON, Shapefile, …) into a styled "
+                    "interactive map or a portable JSON spec.",
+        epilog="examples:\n"
+               "  roadstyle edges.gpkg -o map.html --basemap dark_matter\n"
+               "  roadstyle edges.gpkg --palette carto --basemap positron\n"
+               "  roadstyle edges.gpkg --include motorway trunk primary -o major.html\n"
+               "  roadstyle edges.gpkg --color-by aadt --cmap viridis --width-by 1 6 -f web\n"
+               "  roadstyle edges.gpkg -f spec -o map_data.json   # JSON for your own frontend",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("input", help="road-data file with a road-class column (any CRS).")
+    p.add_argument("-o", "--output",
+                   help="output path (default: input name with the format's extension).")
+    p.add_argument("-f", "--format", default="web",
+                   choices=["web", "folium", "rsjs", "spec", "geojson"],
+                   help="web = self-contained MapLibre map (default); folium = interactive folium "
+                        "HTML; rsjs = standalone roadstyle.js page; spec = JSON spec; "
+                        "geojson = styled GeoJSON.")
+    p.add_argument("--version", action="version", version=f"roadstyle {__version__}")
+
+    style = p.add_argument_group("styling")
+    style.add_argument("--palette", default="highsat", choices=["highsat", "carto"],
+                       help="class palette (default: highsat).")
+    style.add_argument("--basemap", help="the primary base map layer (a key in BASEMAPS; "
+                       "default from settings: voyager).")
+    style.add_argument("--tooltip", nargs="+", metavar="COL",
+                       help="columns to show in the hover tooltip.")
+
+    flt = p.add_argument_group("filtering")
+    flt.add_argument("--include", nargs="+", metavar="TYPE", help="highway types to keep.")
+    flt.add_argument("--exclude", nargs="+", metavar="TYPE", help="highway types to drop.")
+
+    dd = p.add_argument_group("data-driven styling (colour/size by your own column)")
+    dd.add_argument("--color-by", metavar="COLUMN",
+                    help="colour edges by this column instead of road class.")
+    dd.add_argument("--colors", metavar="JSON",
+                    help='categorical map for --color-by, as JSON, e.g. \'{"a":"#f00"}\'.')
+    dd.add_argument("--cmap", help="continuous colormap for a numeric --color-by (e.g. viridis).")
+    dd.add_argument("--vmin", type=float, help="lower bound of the numeric colour ramp.")
+    dd.add_argument("--vmax", type=float, help="upper bound of the numeric colour ramp.")
+    dd.add_argument("--width-by", nargs=2, type=float, metavar=("MIN", "MAX"),
+                    help="scale line width between MIN and MAX px by the numeric --color-by.")
+
+    web = p.add_argument_group("web backend (-f web)")
+    web.add_argument("--view-3d", action="store_true",
+                     help="3D view: tilted camera + extruded, ramped bridge decks.")
+    web.add_argument("--pitch", type=float, help="starting camera tilt in degrees (0-85).")
+    web.add_argument("--bearing", type=float, help="starting camera rotation in degrees.")
+    web.add_argument("--no-arrows", action="store_true", help="hide one-way direction arrows.")
+    web.add_argument("--no-labels", action="store_true", help="hide street-name labels.")
+    web.add_argument("--no-filter", action="store_true", help="hide the road-class filter panel.")
+    web.add_argument("--no-basemap-switcher", action="store_true",
+                     help="hide the in-map base-layer dropdown.")
+    web.add_argument("--tiles", action="store_true",
+                     help="pack the roads as an embedded-PMTiles vector tileset instead of "
+                          "inline GeoJSON (client-side scale for big networks; needs the "
+                          "'tiles' extra).")
+    web.add_argument("--no-compress", action="store_true",
+                     help="write the map data as plain JSON instead of gzipped blobs "
+                          "(bigger files; for very old browsers without DecompressionStream).")
+
+    src = p.add_argument_group("input")
+    src.add_argument("--highway-col", default="highway",
+                     help="name of the road-class column (default: highway).")
+    src.add_argument("--layer", help="layer to read from a multi-layer file (e.g. a GPKG).")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``roadstyle`` console script. Returns a process exit code."""
+    args = _build_parser().parse_args(argv)
+
+    in_path = Path(args.input)
+    if not in_path.exists():
+        print(f"roadstyle: input file not found: {in_path}", file=sys.stderr)
+        return 2
+
+    out_path = Path(args.output) if args.output else in_path.with_suffix(_EXT[args.format])
+
+    colors = None
+    if args.colors:
+        try:
+            colors = json.loads(args.colors)
+        except json.JSONDecodeError as e:
+            print(f"roadstyle: --colors is not valid JSON: {e}", file=sys.stderr)
+            return 2
+
+    # Imported lazily so `roadstyle --version` / `--help` stay fast and don't pull in geopandas.
+    from .edges import load_edges
+    from .emit import save, save_spec, to_geojson
+    from .filters import filter_edges
+    from .render import render_edges
+
+    try:
+        edges = load_edges(str(in_path), class_col=args.highway_col, layer=args.layer)
+        g = edges.gdf
+        col = edges.class_col
+
+        if args.include or args.exclude:
+            g = filter_edges(g, include=args.include, exclude=args.exclude, highway_col=col)
+
+        # Styling keywords shared by every output path; drop the ones the user didn't set so each
+        # function keeps its own defaults.
+        style_kw = {
+            "palette": args.palette, "highway_col": col,
+            "color_by": args.color_by, "colors": colors, "cmap": args.cmap,
+            "vmin": args.vmin, "vmax": args.vmax,
+            "width_by": tuple(args.width_by) if args.width_by else None,
+            "basemap": args.basemap, "tooltip": args.tooltip,
+        }
+        style_kw = {k: v for k, v in style_kw.items() if v is not None}
+
+        if args.format == "web":
+            web_kw = {"arrows": not args.no_arrows, "labels": not args.no_labels,
+                      "filter_control": not args.no_filter,
+                      "basemap_switcher": not args.no_basemap_switcher,
+                      "compress": not args.no_compress,
+                      "tiles": args.tiles,
+                      "view_3d": args.view_3d}
+            if args.pitch is not None:
+                web_kw["pitch"] = args.pitch
+            if args.bearing is not None:
+                web_kw["bearing"] = args.bearing
+            render_edges(g, backend="web", **style_kw, **web_kw).save(str(out_path))
+        elif args.format == "folium":
+            render_edges(g, backend="folium", **style_kw).save(str(out_path))
+        elif args.format == "rsjs":
+            save(g, str(out_path), **style_kw)
+        elif args.format == "spec":
+            save_spec(g, str(out_path), **style_kw)
+        elif args.format == "geojson":
+            out_path.write_text(json.dumps(to_geojson(g, **style_kw)), encoding="utf-8")
+    except (ValueError, KeyError, FileNotFoundError) as e:
+        print(f"roadstyle: {e}", file=sys.stderr)
+        return 1
+
+    print(f"wrote {out_path}  ({len(g):,} edges, {args.format})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())