roadstyle

roadstyle

用 Python 创建精美的交互式道路地图。
一个离线 HTML 文件，包含真实的道路制图、Google Street View 和 JavaScript API。

安装 · 快速开始 · 图库 · 实时地图 · AI Agent · 文档

为什么选择 roadstyle

• 真实的道路制图。 包括描边和填充、随缩放变化的宽度、街道名称、单行道箭头、隧道绘制在下方、桥梁绘制在上方，以及可选的 3D 桥面。
• 一个离线文件。 地图、数据和样式都在一个 HTML 页面中：无需服务即可打开，也可以通过电子邮件发送，或放到任何网站上。
• 内置 Street View。 点击任意道路，即可在 Google Street View 中查看，并面向道路的延伸方向。
• 支持任意道路数据。 GeoDataFrame、文件、DuckDB、Arrow、osmnx 或 duckOSM。
• 按数据着色。 可根据速度、交通流量或任意列着色，并提供图例和着色方式菜单。
• 可脚本化。 提供 window.rs* JavaScript API 和事件，可用于构建自己的仪表板。
• 适用于 AI Agent。 提供 MCP 服务和 Agent 技能。

安装

pip install roadstyle              # core
pip install "roadstyle[all]"       # + studio, numeric ramps, vector tiles, lonboard, DuckDB, …

Python ≥ 3.10。单独的可选依赖和开发环境配置请参阅：安装。

快速开始

从 OpenStreetMap 获取数据，无需准备数据。 可查询任意地点，使用 osmnx（pip install osmnx）：

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")

使用自己的数据。 支持任意包含线几何和 highway 列的文件或 GeoDataFrame：

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)

更多样式：

rs.render_edges(edges, basemap="dark_matter", view_3d=True)            # dark, 3D bridge decks
rs.render_edges(edges, palette="carto", basemap="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=True)                                     # 100k+ edges
rs.render_dashboard(edges).save("dashboard.html")                      # map + query sidebar
rs.render_street_view(edges).save("street_view.html")                  # map and Street View side by side

没有安装 Python？运行 roadstyle edges.gpkg -o map.html --basemap dark_matter，或者在 workbench 中逐步操作：pip install "roadstyle[studio]" && roadstyle studio。

图库

道路地图风格 rs.render_edges(edges)	桥梁和隧道 rs.render_edges(edges)	按数据着色 color_by="maxspeed_kmh"
3D 桥梁 view_3d=True	街景 点击道路	仪表板 rs.render_dashboard(edges)

每种风格均附带代码：图库。

输入内容

只需要 geometry 和 highway。其他列可启用相应功能：

duckOSM（duckosm export-gis）可准确导出此格式；osmnx 的边数据也可直接使用：rs.render_edges(ox.graph_to_gdfs(G, nodes=False))。

通过 JavaScript 驱动

保存的页面会公开 window.rs* 函数和 rs:* 事件：

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));

所有函数和事件详见：JavaScript API。

面向 AI Agent

MCP 服务。 让任何支持 MCP 的 AI 应用（Claude Code、Claude Desktop、Cursor 等）无需编写代码即可绘制道路地图：render_place("Tartu, Estonia")、render_file("roads.gpkg") 和 snapshot。每次调用都会保存一张 HTML 地图，并返回其路径以及 Agent 可以查看的 PNG 预览。

claude mcp add roadstyle -- uvx roadstyle-mcp

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

Claude Code 插件。 一次安装即可使用 MCP 服务和下方的技能：

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

适用于会编写代码的 Agent：

• skills/roadstyle/SKILL.md：供使用 roadstyle 的 Agent 使用的技能（包含一次调用、数据约定、JS API 和注意事项）。 为 Claude Code 安装：

  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：供参与此代码库开发的 Agent 使用。
• llms.txt：面向大模型的文档站点链接列表。

API 密钥

两个密钥都是可选的。roadstyle 无需密钥也能运行，只是功能会少一些。

• CARTO，用于默认底图。没有密钥时，地图图块会显示 API KEY REQUIRED；请设置 CARTO_API_KEY，或使用无需密钥的底图（esri_street、esri_dark_gray、osm、blank）。
• Google Maps，用于街景。无需密钥即可使用街景。添加密钥后会启用 Linked 模式：显示真实全景，地图标记会随你移动和转向。

export CARTO_API_KEY="…"                                          # environment variable

{ "config": { "api_keys": { "carto": "…" } } }

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

更多信息：设置与底图 · Google Street View。

文档

khoshkhah.github.io/roadstyle，每个页面都提供可交互地图。

构建基础

• MapLibre GL JS（BSD-3-Clause）负责绘制所有网页地图：roadstyle 编写其样式和数据，并将 MapLibre 的副本内嵌到每个已保存的页面中，以便离线打开。
• OpenStreetMap 数据（© OpenStreetMap 贡献者，ODbL）和 openstreetmap-carto 样式；roadstyle 遵循其中的道路类别、颜色和宽度设置。
• HiGHS 通过 SciPy 求解道路绘制的叠放顺序。
• GeoPandas 和 Shapely 用于处理几何数据；lonboard（deck.gl）和 folium 用于笔记本后端。

许可证

MIT。底图图块来自第三方服务（CARTO、OSM、Esri），各自有不同的署名要求和使用条款。