roadstyle

[roadstyle logo]

roadstyle

Beautiful, interactive road maps from Python.
One offline HTML file with real road cartography, Google Street View and a JavaScript API.

[PyPI] [Python versions] [Tests] [Docs] [License: MIT]

Install · Quickstart · Gallery · Live map · AI agents · Documentation

[The standard dashboard on a desktop: Monaco on the OpenFreeMap Positron base map, a road selected in the panel at the left, and the toolbox at the right edge] [The dashboard on a phone: the one-row bar at the top, the map, and the panel as a bottom sheet]

[A roadstyle map of Monaco in 3D: bridges, tunnels and roundabouts drawn in order, Rue de la Colle selected, and the floating Street View window showing it]

Why roadstyle

• Real road cartography. Casing and fill, widths that change with zoom, street names, one-way arrows, tunnels drawn under and bridges over, and optional 3D bridge decks.
• One offline file. Map, data and styling in a single HTML page: open it without a server, email it, or put it on any website.
• Street View built in. Click any road to see it in Google Street View, facing the way it runs.
• Any road data. A GeoDataFrame, a file, DuckDB, Arrow, osmnx or duckOSM.
• Colour by your data. Speed, traffic or any column, with a legend and a menu of colourings.
• Scriptable. A window.rs* JavaScript API and events for your own dashboard, and shared parts for its panel: a level editor and a design panel (themes, road colours and widths, names, layers) that any page can open.
• Ready for AI agents. An MCP server and an agent skill.

What is new in 0.29.0

• Ask, an AI agent in the side panel: a question in words becomes SQL on the page's data, an answer, a table and roads on the map. It uses the person's own key of a free service (Gemini, Groq, OpenRouter, Z.ai) or of Claude, and Auto goes to the next service or model when one cannot answer (guide).
• The data dock: a SQL line over a table of the result in the bottom dock; the roads of the result light on the map (guide).
• Charts and more dashboard parts: rs.chart, the editor frame rs.frame, a colour picker and the parts that duckOSM Studio asked for (guide).
• The level editor has the tabs Road ends and Stacking, and adds rules from files.

What is new in 0.28.0

• The design panel is a dashboard part: themes, road colours and widths, names and layers, in any page with a dashboard (guide).
• 3D buildings: solid by default (a road behind a building does not show through the roof), an Opacity slider and buildings_opacity=, and the far buildings of a tilted map.
• The open card has an accent ring and an accent title.

What is new in 0.27.0

• The dashboard's panel starts empty, and a page adds what it needs: its own HTML, the query box or the road card, with dashboard={"panel": {"sections": [...]}} or rs.sections.add. The map of a dashboard has the defaults of a map page. This is a breaking change: see Migrate a dashboard.
• Cards: one standard for the panel. A section with a label is a card, with or without a background (background: False), that folds or not (fold: True). Every card has the same width, gap, padding and title row, and the "?" of rs.help.button is at the end of the title row.
• Every part of the dashboard follows the dark theme, and every scroll area scrolls the same way as the panel.
• Street View: Coverage is an icon after the provider switch, and the close button stays at the top right.

What is new in 0.26.3

• A dashboard manual. Two pages with maps that run: Dashboards for Python and JavaScript. Each JavaScript example has a Run button.
• The two directions of a two-way road are two halves of the road at every zoom. A colour on one direction does not hide the other.
• Fewer arrows on a tiled page, and correct arrows on a page with a vector base map. Monaco, zoom 16.5: 9 arrows, not 85.
• Street View: the coverage shows on any road, and the header of the window keeps the name of the road. duckosm.page draws the base map's textures and icons, and dashboard=False gives the dashboard without a panel.

What is new in 0.26.1

• One accent colour. The dashboard uses the Sonocount teal in the light and the dark theme, defined once. The corner box has the shape of the bar, a button with a text shows no tooltip box, and every tool of a phone's one-row bar can be reached.
• Street View docked, and a dashboard with no panel. street_view="dock" puts Street View beside the map with a divider that you drag. dashboard={"panel": None} gives a map with the toolbox only.
• Help and folding in the panel. rs.help.button adds a "?" button with its own words to a card or a label, all of them open one window. A Collapse all / Expand all control folds the panel's sections. The level editor has a "?" help window with two links to the levels guide.
• Fix: a page that starts in the dark theme no longer shows the error "Style is not done loading".

What is new in 0.26.0

• A standard dashboard and toolbox. rs.render_dashboard(edges) makes a map with one panel and one bar of tools: navigate (zoom, turn and tilt in one box), road filter, base maps, colour and legend, settings and credits. A tool that the page cannot use is grey, and its tooltip says why. The toolbox is at the right edge and the panel at the left. On a phone the bar is one row that you move sideways, and the panel is a bottom sheet.
• Seven base maps, no key. OpenFreeMap Liberty and Positron (the default), OpenStreetMap, Esri Gray, Esri Streets, Esri Satellite and Blank, each with its dark twin when it has one. The CARTO maps are gone, so no base map needs a key. The theme switch also turns the style's own layers dark.
• Tiles by default, one rule. Every page keeps its roads as MLT vector tiles to zoom 16, with one road layer for every zoom. The page, the browser worker, export_style and roadstyle tiles all use the same tiling rule. tiles=False gives GeoJSON roads, and tile_format="mvt" gives MVT.
• The level editor is in the panel. roadstyle levels edit AREA_DIR opens it from the Rust program. It uses the page's standard panel, with an apply bar, red and blue picks, the area boundary (levels make --boundary) and edits.csv in the History tab.
• Shared dashboard parts. Help window, hover box, tabs, number tiles, tables, charts and chips are in the panel's own look, in both themes. rs.classify makes colour classes for roads.

[The dashboard in the dark theme with the OpenFreeMap Fiord base map: Monaco, one road selected]

More: What is new in 0.28.0 · Dashboard layout · Dashboard parts · Big networks · Move a script from 0.25 · Documentation.

Install

pip install roadstyle              # corepip install "roadstyle[all]"       # + studio, DuckDB, …

Python ≥ 3.10. Individual extras and the dev setup: Install.

Quickstart

From OpenStreetMap, no data needed. Any place, with osmnx (pip install osmnx):

import osmnx as oximport roadstyle as rs
G = ox.graph_from_place("Tartu, Estonia", network_type="drive", simplify=False)G = ox.simplify_graph(G, edge_attrs_differ=["bridge", "tunnel"])   # keep tunnels and bridges apartrs.render_edges(ox.graph_to_gdfs(G, nodes=False)).save("tartu.html")

From your own data. Any file or GeoDataFrame with line geometry and a highway column:

import geopandas as gpdimport roadstyle as rs
edges = gpd.read_file("edges.gpkg")        # LineStrings + a `highway` column, any CRSrs.render_edges(edges).save("map.html")    # open map.html: no server (Street View needs one)

More looks:

rs.render_edges(edges, basemap="ofm_dark", view_3d=True)                # dark, 3D bridge decksrs.render_edges(edges, palette="carto", basemap="ofm_positron")        # the classic OSM lookrs.render_edges(edges, color_by="aadt", cmap="viridis")                # colour by your datars.render_edges(edges, palette="mono", color_options={                 # several colourings,    "Traffic": {"color_by": "aadt", "cmap": "viridis"},                #   switched in the browser    "Speed":   {"color_by": "maxspeed_kmh", "cmap": "magma"}})rs.render_edges(edges, tiles=False)                                    # GeoJSON roads (MLT tiles are the default)rs.render_dashboard(edges).save("dashboard.html")                      # map + panel + the standard toolboxrs.render_street_view(edges).save("street_view.html")                  # map and Street View side by side

No Python? roadstyle edges.gpkg -o map.html --basemap ofm_dark, or click through it in the workbench: pip install "roadstyle[studio]" && roadstyle studio.

Gallery

Every look with its code: the gallery.

What goes in

Only geometry and highway are required. Other columns switch features on:

duckOSM (duckosm export-gis) exports exactly this, and osmnx edges work as they are: rs.render_edges(ox.graph_to_gdfs(G, nodes=False)).

Drive it from JavaScript

The saved page exposes window.rs* functions and rs:* events:

const ids = rsQuery(p => p.maxspeed_kmh > 30); // feature ids whose properties matchrsColor(ids, "#ff00aa");  rsFocus(ids);       // paint them, fit the cameradocument.addEventListener("rs:select", e => console.log(e.detail.properties));

Every function and event: JavaScript API.

For AI agents

MCP server. Lets any MCP-capable AI app (Claude Code, Claude Desktop, Cursor, …) draw road maps without writing code: render_place("Tartu, Estonia"), render_file("roads.gpkg") and snapshot. Each saves an HTML map and returns its path plus a PNG preview the agent can look at.

claude mcp add roadstyle -- uvx roadstyle-mcp

{"mcpServers": {"roadstyle": {"command": "uvx", "args": ["roadstyle-mcp"]}}}

Claude Code plugin. The MCP server and the skill below in one install:

/plugin marketplace add Khoshkhah/roadstyle/plugin install roadstyle@roadstyle

For agents that write code:

• skills/roadstyle/SKILL.md: a skill for agents that use roadstyle (the one call, the data contract, the JS API, the traps). Install it for Claude Code:
  bash

  mkdir -p ~/.claude/skills/roadstyle && curl -fsSL -o ~/.claude/skills/roadstyle/SKILL.md \  https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/skills/roadstyle/SKILL.md

• AGENTS.md: for agents working on this repo.
• llms.txt: the docs site as a link list for LLMs.

API keys

The key is optional. roadstyle works without it, just with less. The base maps need no key.

• Google Maps, for Street View. Street View works with no key. A key adds a Linked mode: a real panorama, with the map marker walking and turning with you.

rs.render_edges(edges, street_view_key="AIza…")         # the floating Street View windowrs.render_street_view(edges, street_view_key="AIza…")   # the side-by-side page

More: settings & base maps · Google Street View.

Documentation

khoshkhah.github.io/roadstyle, with live maps on every page.

Built on

• MapLibre GL JS (BSD-3-Clause) draws every web map: roadstyle writes its style and data, and a copy of MapLibre is inlined in each saved page so it opens offline.
• OpenStreetMap data (© OpenStreetMap contributors, ODbL) and the openstreetmap-carto style, whose road classes, colours and widths roadstyle follows.
• HiGHS, through SciPy, is the optional Python solver of which road is drawn on top. The default solver is in Rust.
• GeoPandas and Shapely for the geometry.

License

MIT. Base-map tiles come from third-party services (OpenFreeMap, OSM, Esri) with their own attribution and terms.