Metadata-Version: 2.4
Name: roadstyle
Version: 0.26.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Dist: geopandas
Requires-Dist: shapely
Requires-Dist: pyyaml
Requires-Dist: scipy
Requires-Dist: ortools
Requires-Dist: pyarrow
Requires-Dist: roadstyle[basemaps,duckdb,arrow,studio] ; extra == 'all'
Requires-Dist: pyarrow ; extra == 'arrow'
Requires-Dist: xyzservices ; extra == 'basemaps'
Requires-Dist: roadstyle[all] ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: mypy ; extra == 'dev'
Requires-Dist: mkdocs-material ; extra == 'docs'
Requires-Dist: mkdocs-redirects ; extra == 'docs'
Requires-Dist: duckdb ; extra == 'duckdb'
Requires-Dist: mcp>=2.2,<3 ; extra == 'mcp'
Requires-Dist: osmnx ; extra == 'mcp'
Requires-Dist: playwright ; extra == 'mcp'
Requires-Dist: streamlit ; extra == 'studio'
Provides-Extra: all
Provides-Extra: arrow
Provides-Extra: basemaps
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: duckdb
Provides-Extra: mcp
Provides-Extra: studio
License-File: LICENSE
Summary: Road cartography for Python: turn road edges into styled, interactive, offline HTML maps (MapLibre) with a JavaScript API
Keywords: openstreetmap,osm,roads,cartography,map,visualization,geopandas,leaflet,maplibre
Home-Page: https://khoshkhah.github.io/roadstyle/
Author: Kaveh
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/Khoshkhah/roadstyle/blob/main/CHANGELOG.md
Project-URL: Documentation, https://khoshkhah.github.io/roadstyle/
Project-URL: Homepage, https://github.com/Khoshkhah/roadstyle
Project-URL: Source, https://github.com/Khoshkhah/roadstyle

<p align="center">
  <img src="https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/assets/roadstyle-logo.svg" alt="roadstyle logo" width="96">
</p>

<h1 align="center">roadstyle</h1>

<p align="center">
  <b>Beautiful, interactive road maps from Python.</b><br>
  One offline HTML file with real road cartography, Google Street View and a JavaScript API.
</p>

<p align="center">
  <a href="https://pypi.org/project/roadstyle/"><img src="https://img.shields.io/pypi/v/roadstyle.svg" alt="PyPI"></a>
  <a href="https://pypi.org/project/roadstyle/"><img src="https://img.shields.io/pypi/pyversions/roadstyle.svg" alt="Python versions"></a>
  <a href="https://github.com/Khoshkhah/roadstyle/actions/workflows/test.yml"><img src="https://github.com/Khoshkhah/roadstyle/actions/workflows/test.yml/badge.svg?branch=main" alt="Tests"></a>
  <a href="https://khoshkhah.github.io/roadstyle/"><img src="https://img.shields.io/badge/docs-khoshkhah.github.io%2Froadstyle-ff6b35.svg" alt="Docs"></a>
  <a href="https://github.com/Khoshkhah/roadstyle/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
</p>

<p align="center">
  <a href="#install">Install</a> ·
  <a href="#quickstart">Quickstart</a> ·
  <a href="#gallery">Gallery</a> ·
  <a href="https://khoshkhah.github.io/roadstyle/maps/live.html"><b>Live map</b></a> ·
  <a href="#for-ai-agents">AI agents</a> ·
  <a href="https://khoshkhah.github.io/roadstyle/">Documentation</a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/docs/img/gallery/dashboard.jpg" alt="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" width="68%">
  <img src="https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/docs/img/gallery/dashboard_phone.jpg" alt="The dashboard on a phone: the one-row bar at the top, the map, and the panel as a bottom sheet" width="22%">
</p>

![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](https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/docs/img/hero.jpg)

## 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](https://osmnx.readthedocs.io/)
  or [duckOSM](https://github.com/Khoshkhah/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.
- **Ready for AI agents.** An MCP server and an agent skill.

## 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.

<p align="center">
  <img src="https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/docs/img/gallery/dashboard_dark.jpg" alt="The dashboard in the dark theme with the OpenFreeMap Fiord base map: Monaco, one road selected" width="80%">
</p>

More: [What is new in 0.26.1](https://khoshkhah.github.io/roadstyle/#what-is-new-in-0261) ·
[Dashboard layout](https://khoshkhah.github.io/roadstyle/guides/dashboard-layout/) ·
[Dashboard parts](https://khoshkhah.github.io/roadstyle/guides/dashboard-parts/) ·
[Big networks](https://khoshkhah.github.io/roadstyle/guides/big-networks/) ·
[Move a script from 0.25](https://khoshkhah.github.io/roadstyle/guides/migrating-dashboard/) ·
[Documentation](https://khoshkhah.github.io/roadstyle/).

## Install

```bash
pip install roadstyle              # core
pip install "roadstyle[all]"       # + studio, DuckDB, …
```

Python ≥ 3.10. Individual extras and the dev setup: [Install](https://khoshkhah.github.io/roadstyle/get-started/#install).

## Quickstart

**From OpenStreetMap, no data needed.** Any place, with [osmnx](https://osmnx.readthedocs.io/) (`pip install osmnx`):

```python
import osmnx as ox
import 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 apart
rs.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:

```python
import geopandas as gpd
import roadstyle as rs

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

**More looks:**

```python
rs.render_edges(edges, basemap="ofm_dark", view_3d=True)                # dark, 3D bridge decks
rs.render_edges(edges, palette="carto", basemap="ofm_positron")        # the classic OSM look
rs.render_edges(edges, color_by="aadt", cmap="viridis")                # colour by your data
rs.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 toolbox
rs.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

<table>
<tr>
<td width="33%" valign="top"><a href="https://khoshkhah.github.io/roadstyle/gallery/"><img src="https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/docs/img/gallery/road_look.jpg" alt="The road map look" width="100%"></a><br><b>The road map look</b><br><sub><code>rs.render_edges(edges)</code></sub></td>
<td width="33%" valign="top"><a href="https://khoshkhah.github.io/roadstyle/gallery/"><img src="https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/docs/img/gallery/bridges_tunnels.jpg" alt="Bridges and tunnels" width="100%"></a><br><b>Bridges and tunnels</b><br><sub><code>rs.render_edges(edges)</code></sub></td>
<td width="33%" valign="top"><a href="https://khoshkhah.github.io/roadstyle/gallery/"><img src="https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/docs/img/gallery/colour_by_data.jpg" alt="Colour by your data" width="100%"></a><br><b>Colour by your data</b><br><sub><code>color_by="maxspeed_kmh"</code></sub></td>
</tr>
<tr>
<td width="33%" valign="top"><a href="https://khoshkhah.github.io/roadstyle/gallery/"><img src="https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/docs/img/gallery/bridges_3d.jpg" alt="3D bridges" width="100%"></a><br><b>3D bridges</b><br><sub><code>view_3d=True</code></sub></td>
<td width="33%" valign="top"><a href="https://khoshkhah.github.io/roadstyle/gallery/"><img src="https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/docs/img/gallery/street_view.jpg" alt="Street View" width="100%"></a><br><b>Street View</b><br><sub><code>click a road</code></sub></td>
<td width="33%" valign="top"><a href="https://khoshkhah.github.io/roadstyle/gallery/"><img src="https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/docs/img/gallery/dashboard.jpg" alt="Dashboard" width="100%"></a><br><b>Dashboard</b><br><sub><code>rs.render_dashboard(edges)</code></sub></td>
</tr>
</table>

Every look with its code: **[the gallery](https://khoshkhah.github.io/roadstyle/gallery/)**.

## What goes in

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

| Column | Powers |
|---|---|
| `geometry` (LineString, any CRS) | the edges. Each edge is **directed**: a two-way road is two edges with reversed geometry |
| `highway` (OSM class) | colour, width, casing, draw order |
| `name` | street labels, popup title |
| `oneway` | direction arrows |
| `bridge` / `tunnel` / `layer` | grade separation: tunnels below, bridges on decks above |
| `edge_id` | popups; 64-bit ids stay exact |
| anything else | shown in the popup, queryable from JavaScript |

[duckOSM](https://github.com/Khoshkhah/duckOSM) (`duckosm export-gis`) exports exactly this, and
[osmnx](https://osmnx.readthedocs.io/) 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:

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

Every function and event: [JavaScript API](https://khoshkhah.github.io/roadstyle/reference/javascript/).

## 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.

```bash
claude mcp add roadstyle -- uvx roadstyle-mcp
```

<details>
<summary>Claude Desktop, and where the maps go</summary>

In `claude_desktop_config.json`:

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

Maps are saved in `~/roadstyle-maps/`. The PNG preview needs Chromium, once:
`uvx --from roadstyle-mcp playwright install chromium`.

</details>

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

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

**For agents that write code:**

- [`skills/roadstyle/SKILL.md`](https://github.com/Khoshkhah/roadstyle/blob/main/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`](https://github.com/Khoshkhah/roadstyle/blob/main/AGENTS.md): for agents working *on* this repo.
- [`llms.txt`](https://khoshkhah.github.io/roadstyle/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.

<details>
<summary>Setting up the Google Maps key</summary>

Street View works with no key: the keyless Google embed. With a
Google **Maps JavaScript API** key, the Street View panel and window get a **Linked / Classic**
switch. Linked is a real panorama: the map marker walks and turns with you, and only Google's own
street photos are shown. Classic is the keyless embed. To get a key:

1. In the [Google Cloud console](https://console.cloud.google.com/), create a project and enable
   **Maps JavaScript API** (Google asks for a billing account on the project).
2. Under *APIs & Services > Credentials*, create an **API key**.
3. Restrict it: *Application restrictions* = **Websites**, listing your site's addresses
   (e.g. `https://example.com/*`); *API restrictions* = **Maps JavaScript API** only.

Then pass it in:

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

The key is written into the page, as every browser key is, so the site restriction in step 3 is
what protects it. It also means Linked works only on the addresses you listed: to try it on
`localhost`, add `http://localhost:*/*` to the list. Keep the key out of git, for example in an
environment variable.

</details>

More: [settings & base maps](https://khoshkhah.github.io/roadstyle/reference/settings/#base-maps-api-keys) ·
[Google Street View](https://khoshkhah.github.io/roadstyle/guides/street-view/).

## Documentation

**[khoshkhah.github.io/roadstyle](https://khoshkhah.github.io/roadstyle/)**, with live maps on every page.

| Where | What you find |
|---|---|
| **[Get started](https://khoshkhah.github.io/roadstyle/get-started/)** | install, a first map, what your data needs |
| **Guides** | [style the roads](https://khoshkhah.github.io/roadstyle/guides/style/) · [colour by your data](https://khoshkhah.github.io/roadstyle/guides/colour/) · [your own layers](https://khoshkhah.github.io/roadstyle/guides/overlays/) · [Google Street View](https://khoshkhah.github.io/roadstyle/guides/street-view/) · [big networks](https://khoshkhah.github.io/roadstyle/guides/big-networks/) · [dashboards & JavaScript](https://khoshkhah.github.io/roadstyle/guides/dashboards/) · [dashboard layout](https://khoshkhah.github.io/roadstyle/guides/dashboard-layout/) · [dashboard parts](https://khoshkhah.github.io/roadstyle/guides/dashboard-parts/) · [which road is on top](https://khoshkhah.github.io/roadstyle/guides/levels/) · [on a website](https://khoshkhah.github.io/roadstyle/guides/website/) |
| **[Gallery](https://khoshkhah.github.io/roadstyle/gallery/)** | a picture and one line of code per look |
| **[Rust engine](https://khoshkhah.github.io/roadstyle/rust/)** | the one engine: the style, the tiles, the levels and the page; the browser package and the crates |
| **Reference** | [every parameter](https://khoshkhah.github.io/roadstyle/reference/parameters/) · [JavaScript API](https://khoshkhah.github.io/roadstyle/reference/javascript/) · [settings & base maps](https://khoshkhah.github.io/roadstyle/reference/settings/) · [command line](https://khoshkhah.github.io/roadstyle/reference/cli/) |
| **[Changelog](https://github.com/Khoshkhah/roadstyle/blob/main/CHANGELOG.md)** | what changed in each release |

## Built on

- **[MapLibre GL JS](https://maplibre.org/)** (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](https://www.openstreetmap.org/copyright)** data (© OpenStreetMap contributors, ODbL) and the
  **[openstreetmap-carto](https://github.com/gravitystorm/openstreetmap-carto)** style, whose road classes,
  colours and widths roadstyle follows.
- **[HiGHS](https://highs.dev/)**, through [SciPy](https://scipy.org/), is the optional Python solver of which road is drawn on top. The default solver is in Rust.
- **[GeoPandas](https://geopandas.org/)** and **[Shapely](https://shapely.readthedocs.io/)** for the geometry.

## License

[MIT](https://github.com/Khoshkhah/roadstyle/blob/main/LICENSE). Base-map tiles come from
third-party services (OpenFreeMap, OSM, Esri) with their own attribution and terms.

