mapstyle

A whole OpenStreetMap map in one offline HTML page:
the roads for driving, walking and cycling over a full base map, from one duckOSM database.

Documentation · Live map · Get started · Gallery · JavaScript API

Quick start

pip install mapstyle "duckosm @ git+https://github.com/Khoshkhah/duckOSM"

curl -LO https://download.geofabrik.de/europe/monaco-latest.osm.pbf
duckosm build --pbf monaco-latest.osm.pbf -o monaco.duckdb \
              -m driving -m walking -m cycling
mapstyle monaco.duckdb          # -> monaco_all.html: one file, opens offline

import mapstyle as ms

ms.render_map("monaco.duckdb").save("monaco.html")                    # the whole map
ms.render_map("monaco.duckdb", mode="walking", paths="komoot")        # paths in front
ms.render_map("monaco.duckdb", theme="grey")                          # a quiet map for data
ms.render_map("monaco.duckdb", planner=True).save("planner.html")     # a route planner demo
ms.render_map("monaco.duckdb", dashboard=True).save("dashboard.html") # a dashboard

What you get

• Every travel mode on one map, or one brought to the front: all, driving, walking, cycling; four looks for paths (google, osm, komoot, cyclosm); and three themes for the whole map: osm (detailed), google (clean), grey (quiet, for your data on top).
• A full base map from the same database: the sea, land use with openstreetmap.org's textures, water, buildings, railways, parking, transit, traffic lights and crossings. No tile server, no API key.
• Roads drawn right at junctions: two-way roads as two lanes, bridges and overpasses over, tunnels under, a footway or crossing never over a street; zebra crossings and traffic lights are drawn over their street, at its level, so on a bridge or in a tunnel they follow it. The drawing order of the roads is roadstyle's: a casing number and a fill number for every road, read from the database when duckosm levels stored them, else computed while the page is made, so a joint of roads at different levels shows no ring.
• A route planner demo: drag a start and an end and see duckOSM's route on the map (routing itself is duckOSM's job).
• A dashboard: filter by mode, road class and layer, colour by mode, inspect what you click.
• A JavaScript API: every page is a roadstyle page (rsQuery, rsFilter, rsColor, …) plus rsSetModes, rsSetKinds, rsSetInteraction and rsSetBuildings3D; 3D, Street View and vector tiles for large areas come with it.

Walking: paths in front	A raised walkway over a roundabout
The route planner demo	The dashboard

How it fits together

The look is data: four YAML files in src/mapstyle/styles/ (travel modes, path styles, colours, layers). See Styles.

Command line

mapstyle DB [-o OUT] [--mode {all,driving,walking,cycling}] [--paths {google,osm,komoot,cyclosm}]
            [--theme {osm,google,grey}]
            [--no-layers] [--planner] [--dashboard] [--tiles] [--basemap BASEMAP]

For AI agents

• Using mapstyle: the agent skill skills/mapstyle/SKILL.md has the install, the one call, the options, the JavaScript API and the traps in one page. In Claude Code: /plugin marketplace add Khoshkhah/mapstyle, then /plugin install mapstyle@mapstyle.
• The docs as text: llms.txt and llms-full.txt (every page, one file).
• Changing mapstyle: AGENTS.md has the commands and the project's rules.

More: AI agents.

Development

git clone https://github.com/Khoshkhah/mapstyle && cd mapstyle
python -m venv .venv && .venv/bin/pip install -e ".[dev,tiles]"
.venv/bin/pytest          # builds a Monaco database with a duckOSM checkout next to this one

Tests look for duckOSM in ../duckOSM (with its .venv), or wherever DUCKOSM_DIR / DUCKOSM_EXE point; MAPSTYLE_TEST_DB reuses a database you already built. Design notes are in docs/design/.

License

MIT. Map data © OpenStreetMap contributors (ODbL); the sea from Overture Maps, built from OpenStreetMap's coastline.