Python renderer for OpenStreetMap with custom icons intended to display as many map features as possible

Map Machine project consists of

• Python OpenStreetMap renderer:
  • SVG map generation,
  • SVG and PNG tile generation,
• Röntgen icon set: unique CC-BY 4.0 map icons.

The idea behind the Map Machine project is to show all the richness of the OpenStreetMap data: to have a possibility to display any map feature represented by OpenStreetMap data tags by means of colors, shapes, and icons. Map Machine is created both for map contributors: to display all changes one made on the map even if they are small, and for map users: to dig down into the map and find every detail that was mapped.

Unlike standard OpenStreetMap layers, Map Machine is a playground for experiments where one can easily try to support any unsupported tag, proposed tagging scheme, tags with little or even single usage, deprecated ones that are still in use.

Map Machine is intended to be highly configurable, so it can generate precise but messy maps for OSM contributors as well as pretty and clean maps for OSM users. It can also use some slow algorithms for experimental features.

Usage example

map-machine render -b 2.284,48.860,2.290,48.865

will automatically download OSM data and write output SVG map of the specified area to out/map.svg. See Map generation.

map-machine tile -b 2.361,48.871,2.368,48.875

will automatically download OSM data and write output PNG tiles that cover the specified area to the out/tiles directory. See Tile generation.

Röntgen icon set

The central feature of the project is Röntgen icon set. It is a set of monochrome 14 × 14 px pixel-aligned icons specially created for Map Machine project. Unlike the Map Machine source code, which is under MIT license, all icons are under CC BY license. So, with the appropriate credit icon set can be used outside the project. Some icons can be used as emoji symbols.

All icons tend to support a common design style, which is heavily inspired by Maki, Osmic, and Temaki.

Feel free to request new icons via issues for whatever you want to see on the map. No matter how frequently the tag is used in OpenStreetMap since the final goal is to cover all tags. However, commonly used tags have priority, other things being equal.

Generate icon grid and sets of individual icons with map-machine icons. It will update doc/grid.svg file, and create SVG files in out/icons_by_id directory where files are named using shape identifiers (e.g. power_tower_portal_2_level.svg) and in icons_by_name directory where files are named using shape names (e.g. Röntgen portal two-level transmission tower.svg). Files from the last directory are used in OpenStreetMap wiki (e.g. File:Röntgen_portal_two-level_transmission_tower.svg).

Map features

Extra icons

Map Machine uses icons to visualize tags for nodes and areas. But unlike other renderers, Map Machine can use more than one icon to visualize an entity and use colors to visualize colour value or other entity properties (like material or genus).

Isometric building shapes

With --buildings isometric or --buildings isometric-no-parts (not set by default), buildings are drawn using isometric shapes for walls and shade in proportion to building:levels, building:min_level, height, and min_height values.

Road lanes

To determine road width Map Machine uses the width tag value or estimates it based on the lanes value. If lane value is specified, it also draws lane separators. This map style is highly inspired by Christoph Hormann's post Navigating the Maze.

Trees

Visualization of tree leaf types (broadleaved or needle-leaved) and genus or taxon by means of icon shapes and leaf cycles (deciduous or evergreen) by means of color.

Viewpoint and camera direction

direction tag values for tourism = viewpoint and camera:direction for man_made = surveillance are rendered with sectors displaying the direction and angle (15º if angle is not specified) or the whole circle for panorama view. Radial gradient is used for surveillance and inverted radial gradient is used for viewpoints.

Power tower design

Visualize design values used with power = tower tag.

Colors

Map icons have colour tag value if it is present, otherwise, icons are displayed with dark grey color by default, purple color for shop nodes, red color for emergency features, and special colors for natural features. Map Machine also takes into account building:colour, roof:colour and other *:colour tags, and uses colour tag value to paint subway lines.

Emergency

Japanese map symbols

Japanese maps usually use special symbols called chizukigou (地図記号) which are different from standard map symbols used in other countries. They can be enabled with --country jp option.

Shape combination

One of the key features of Map Machine is constructing icons from the several shapes.

Masts

For man_made = mast distinguish types (communication, lignting, monitoring, and siren) and construction (freestanding or lattice, and using of guys) are rendered by combining 7 unique icon shapes.

Volcanoes

For natural = volcano status (active, dormant, extinct, or unspecified) and type (stratovolcano, shield, or scorial) are rendered by combining 7 unique icon shapes.

Wireframe view

Creation time mode

Visualize element creation time with --mode time.

Author mode

Every way and node displayed with the random color picked for each author with --mode author.

Installation

Requirements: Python 3.9.

• Install cairo 2D graphic library,
• install GEOS library,
• install Python packages:

pip install .

Map generation

Command render is used to generate SVG map from OpenStreetMap data. You can run it using:

map-machine render \
    -b <min longitude>,<min latitude>,<max longitude>,<max latitude> \
    -o <output file name> \
    -z <OSM zoom level> \
    <other arguments>

Example

map-machine render \
    --boundary-box 2.284,48.860,2.290,48.865 \
    --output out/esplanade_du_trocadéro.svg

will download OSM data to cache/2.284,48.860,2.290,48.865.osm and write an output SVG map of the specified area to out/esplanade_du_trocadéro.svg.

Arguments

plus map configuration options

Tile generation

Command tile is used to generate PNG tiles for slippy maps. To use them, run Map Machine tile server.

plus map configuration options

Generate one tile

Specify tile coordinates:

map-machine tile --tile <OSM zoom level>/<x>/<y>

or specify any geographical coordinates inside a tile:

map-machine tile \
    --coordinates <latitude>,<longitude> \
    --zoom <OSM zoom levels>

Tile will be stored as SVG file out/tiles/tile_ _ _ .svg and PNG file out/tiles/tile_ _ _ .svg , where x and y are tile coordinates. --zoom option will be ignored if it is used with --tile option.

Example:

map-machine tile -c 55.7510637,37.6270761 -z 18

will generate SVG file out/tiles/tile_18_158471_81953.svg and PNG file out/tiles/tile_18_158471_81953.png.

Generate a set of tiles

Specify boundary box to get the minimal set of tiles that covers the area:

map-machine tile \
    --boundary-box <min longitude>,<min latitude>,<max longitude>,<max latitude> \
    --zoom <OSM zoom levels>

The boundary box will be extended to the boundaries of the minimal tileset that covers the area, then it will be extended a bit more to avoid some artifacts on the edges rounded to 3 digits after the decimal point. Map with new boundary box coordinates will be written to the cache directory as SVG and PNG files. All tiles will be stored as SVG files out/tiles/tile_ _ _ .svg and PNG files out/tiles/tile_ _ _ .svg , where x and y are tile coordinates.

Example:

map-machine tile -b 2.361,48.871,2.368,48.875

will generate 36 PNG tiles at zoom level 18 from tile 18/132791/90164 all the way to 18/132796/90169 and two cached files cache/2.360,48.869,2.370,48.877_18.svg and cache/2.360,48.869,2.370,48.877_18.png.

Tile server

Command server is used to run tile server for slippy maps.

map-machine server

Stop server interrupting the process with Ctrl + C.

Example

Create a minimal amount of tiles that cover specified boundary box for zoom levels 16, 17, 18, and 19:

map-machine tile -b 2.364,48.854,2.367,48.857 -z 16-19

Run tile server on 127.0.0.1:8080:

map-machine server

Use JavaScript code for Leaflet:

var map = L.map('mapid').setView([48.8555, 2.3655], 18);

L.tileLayer('http://127.0.0.1:8080/tiles/{z}/{x}/{y}', {
    maxZoom: 19,
    attribution: 'Map data © ' +
        'OpenStreetMap ' +
        'contributors, imagery © ' +
        'Map Machine',
    id: 'map_machine',
    tileSize: 256,
    zoomOffset: 0
}).addTo(map);

HTML code:

<div id="mapid" style="width: 1000px; height: 600px;">div>

Map options

Map configuration options used by render and tile commands:

MapCSS 0.2 generation

Command mapcss is used to generate MapCSS scheme. map-machine mapcss will create out/map_machine_mapcss directory with simple MapCSS 0.2 scheme adding icons from Röntgen icon set to nodes and areas: .mapcss file and directory with icons.

To create MapCSS with Map Machine style also for ways and relations, run map-machine mapcss --ways.

Use Map Machine as JOSM map paint style

• Run map-machine mapcss.
• Open JOSM.
• Go to Preferences → Third tab on the left → Map Paint Styles.
• Active styles: press +.
• URL / File: set path to out/map_machine_mapcss/map_machine.mapcss.

To enable/disable Map Machine map paint style go to View → Map Paint Styles → Map Machine.

Example

Example of using Röntgen icons on top of Mapnik style in JOSM. Map Paint Styles look like this:

• ✓ Mapnik (true)
• ✓ Map Machine