\title {Röntgen}
\page_icon {out/icons_by_id/book.svg}

\b {Röntgen} (or \b {Roentgen} when ASCII is preferred) project consists of

\list
    {simple Python \ref {http://openstreetmap.org} {OpenStreetMap} renderer and tile generator (see \ref {#usage-example} {usage}, \ref {#map-generation} {renderer documentation}, \ref {#tile-generation} {tile generation}),}
    {\ref {#icon-set} {set of CC-BY 4.0 icons} that can be used outside the project.}

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

Unlike standard OpenStreetMap layers, \b {Röntgen is a playground for experiments} where one can easily try to support proposed tags, tags with little or even single usage, deprecated tags.

Röntgen 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, can use slow algorithms for some experimental features.

\2 {Usage example} {usage-example}

\code {roentgen render -b 2.284,48.860,2.290,48.865} {bash}

will automatically download OSM data and write output SVG map of the specified area to \m {out/map.svg}.  See \ref {#map-generation} {Map generation}.

\code {roentgen tile -b 2.361,48.871,2.368,48.875} {bash}

will automatically download OSM data and write output PNG tiles that cover the specified area to \m {out/tiles} directory.  See \ref {#tile-generation} {Tile generation}.

\2 {Map features} {features}

Röntgen features\:
\list
    {detailed icons to display subtypes like \ref {#power-tower-design} {power tower design},}
    {can display multiple icons for one entity to cover more features,}
    {use color to visualize \osm {colour} and other features like plant types,}
    {display \ref {#levels} {primitive 3D shapes} for buildings,}
    {display \ref {#direction} {directions} with gradient sectors,}
    {use width to display roads.}

\3 {Isometric building shapes} {levels}

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

\image {doc/buildings.png} {3D buildings}

\3 {Trees} {trees}

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

/*

Visualization of tree \icon {tree} leaf types (broadleaved \icon {tree_with_leaf} or needleleaved \icon {needleleaved_tree}) and genus or taxon by means of icon shapes and leaf cycles (unknown \color {#98AC64}, deciduous \color {#fcaf3e} or evergreen \color {#688C44}) by means of color. If diameter, circumference, and/or diameter_crown are specified, we draw crown and trunk as circles. We also have special icons for some genus and taxons\: birch (\i {Betula}) \icon {betula}, palm (\i {Arecaceae}) \icon {palm}, maple (\i {Acer}) \icon {tree}\icon {leaf_maple}.

\table
    {{\osm {natural=tree}} {\icon {tree}}}
    {{\osm {leaf_type=broadleaved}} {\icon {tree_with_leaf}}}
    {{\osm {leaf_type=needleleaved}} {\icon {needleleaved_tree}}}
    {{\osm {taxon=Arecaceae}} {\icon {palm}}}
    {{\osm {genus=Betula}} {\icon {betula}}}

\table
    {{} {\color {#98AC64}}}
    {{\osm {leaf_cycle=deciduous}} {\color {#fcaf3e}}}
    {{\osm {leaf_cycle=evergreen}} {\color {#688C44}}}

*/

\image {doc/trees.png} {Trees}

\3 {Viewpoint and camera direction} {direction}

Visualize \osm {direction} tag for \osm {tourism=viewpoint} and \osm {camera:direction} for \osm {man_made=surveillance}.

\image {doc/surveillance.png} {Surveillance}

\3 {Power tower design} {power-tower-design}

Visualize \osm {design} values used with \osm {power=tower} tag.

\image {doc/power_tower_design.png} {Power tower design}
\image {doc/power.png} {Power tower design}

\3 {Emergency} {emergency}

\image {doc/emergency.png} {Emergency}

\3 {Japanese map symbols} {japanese-map-symbols}

There are \ref {https://en.wikipedia.org/wiki/List_of_Japanese_map_symbols} {special symbols} appearing on Japanese maps.

\image {doc/japanese.png} {Japanese map symbols}

\2 {Icon set} {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.  Unlike the Röntgen source code, which is under MIT license, all icons are under \ref {http://creativecommons.org/licenses/by/4.0/} {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 common design style, which is heavily inspired by \ref {https://github.com/mapbox/maki} {Maki}, \ref {https://github.com/gmgeo/osmic} {Osmic}, and \ref {https://github.com/ideditor/temaki} {Temaki}.

Icons are used to visualize tags for nodes and areas.  Unlike other renderers, Röntgen can use more than one icon to visualize an entity and use colors to visualize \osm {colour} value or other entity properties (like \osm {material} or \osm {genus}).

\image {doc/grid.png} {Icons}

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 final goal is to cover all tags.  However, common used tags have priority, other things being equal.

Generate icon grid and sets of individual icons with \m {\command {Test icon generation}}.  It will create \m {out/icon_grid.svg} file, and SVG files in \m {out/icons_by_id} directory where files are named using shape identifiers (e.g. \m {power_tower_portal_2_level.svg}) and in \m {icons_by_name} directory where files are named using shape names (e.g. \m {Röntgen portal two-level transmission tower.svg}).  Files from the last directory are used in OpenStreetMap wiki (e.g. \ref {https://wiki.openstreetmap.org/wiki/File:R%C3%B6ntgen_portal_two-level_transmission_tower.svg} {\m {File:Röntgen_portal_two-level_transmission_tower.svg}}).

\3 {Shape combination} {shape_combination}

Röntgen constructs icons from the shapes extracted from the sketch SVG file.  Some icons consists of just one shape, to construct other it may be necessary to combine two or more shapes.

\image {doc/bus_stop.png} {Bus stop icon combination}

/*

\3 {Icon settings} {icon_settings}

\4 {Japanese map symbols} {japanese-map-symbols}

\table
    {
        {}
        {\code {\{
    include: ['world'],
    exclude: ['jp']
\}} (\ref {https://ideditor.github.io/location-conflation/?locationSet=%7Binclude%3A%20%5B%27world%27%5D%2C%20exclude%3A%20%5B%27jp%27%5D%7D&referrer=nsi} {view map})}
        {\code {\{
    include: ['jp']
\}} (\ref {https://ideditor.github.io/location-conflation/?locationSet=%7Binclude%3A%20%5B%27jp%27%5D%7D&referrer=nsi} {view map})}
    }
    {
        {\m {amenity=post_office}}
        {\icon {envelope} {-}}
        {\icon {japan_post} {-}}
    }
    {
        {\m {amenity=school}} {}
        {\icon {japan_elementary_school} {-}}
    }

\4 {Script direction} {script-direction}

Countries with right-to-left script direction\:

\code {\{include: [
    'ae', 'af', 'bh', 'eg', 'il', 'iq', 'ir', 'jo', 'kw', 'lb', 'om', 'pk',
    'ps', 'qa', 'sa', 'sy', 'ye'
]\}}

*/

\2 {Wireframe view} {wireframe-view}

\3 {Creation time mode} {time_mode}

Visualize element creation time with \m {--mode time}.

\image {doc/time.png} {Creation time mode}

\3 {Author mode} {author_mode}

Every way and node displayed with the random color picked for each author with \m {--mode user-coloring}.

\image {doc/user.png} {Author mode}

\2 {Installation} {installation}

Requirements\: Python 3.9/* or higher*/.

To install all packages, run\:

\code {pip install -r requirements.txt
pip install .} {bash}

\2 {Map generation} {map-generation}

Command \m {render} is used to generates SVG map from OpenStreetMap data.  You can run it using\:

\code {roentgen render \\
    -b \formal {min longitude},\formal {min latitude},\formal {max longitude},\formal {max latitude} \\
    -o \formal {output file name} \\
    -s \formal {osm zoom level} \\
    \formal {other arguments}} {bash}

\3 {Example} {example-2}

\code {roentgen render \\
    --boundary-box 2.284,48.860,2.290,48.865 \\
    --output out/esplanade_du_trocadéro.svg} {bash}

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

\3 {Arguments} {arguments}

\options {render}

+ see \ref {#map-options} {map configuration options}

\2 {Tile generation} {tile-generation}

Command \m {tile} is used to generate PNG tiles for \ref {https://wiki.openstreetmap.org/wiki/Slippy_Map} {slippy maps}.  To use them, run \ref {#tile-server} {Röntgen tile server}.

\options {tile}

+ see \ref {#map-options} {map configuration options}

\3 {Generate one tile} {generate-one-tile}

Specify tile coordinates\:

\code {roentgen tile --tile \formal {OSM zoom level}/\formal {x}/\formal {y}} {bash}

or specify any geographical coordinates inside a tile\:

\code {roentgen tile \\
    --coordinates \formal {latitude},\formal {longitude} \\
    --scales \formal {OSM zoom levels}} {bash}

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

Example\:

\code {roentgen tile -c 55.7510637,37.6270761 -s 18} {bash}

will generate SVG file \m {out/tiles/tile_18_158471_81953.svg} and PNG file \m {out/tiles/tile_18_158471_81953.png}.

\3 {Generate a set of tiles} {generate-a-set-of-tiles}

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

\code {roentgen tile \\
    --boundary-box \formal {min longitude},\formal {min latitude},\formal {max longitude},\formal {max latitude} \\
    --scales \formal {OSM zoom levels}} {bash}

Boundary box will be extended to the boundaries of the minimal tile set 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 \m {out/tiles/tile_<zoom level>_<x>_<y>.svg} and PNG files \m {out/tiles/tile_<zoom level>_<x>_<y>.svg}, where \m {x} and \m {y} are tile coordinates.

Example\:

\code {roentgen tile -b 2.361,48.871,2.368,48.875} {bash}

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

\2 {Tile server} {tile-server}

Command \m {server} is used to run tile server for slippy maps.

\code {roentgen server}

Stop server interrupting process with \kbd {Ctrl} + \kbd {C}.

\3 {Example} {example}

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

\code {roentgen tile -b 2.364,48.854,2.367,48.857 -s 16-19} {bash}

Run tile server on 127.0.0.1\:8080\:

\code {roentgen server} {bash}

Use JavaScript code for \ref {https://leafletjs.com/} {Leaflet}\:

\code {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 &copy; ' +
        '<a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> ' +
        'contributors, imagery &copy; ' +
        '<a href="https:/github.com/enzet/Roentgen">Röntgen</a>',
    id: 'roentgen',
    tileSize: 256,
    zoomOffset: 0
\}).addTo(map);} {js}

\2 {Map options} {map-options}

Map configuration options used by \m {render} and \m {tile} commands:

\options {map}

\2 {MapCSS 0.2 generation} {mapcss-0-2-generation}

Command \m {mapcss} is used to generate MapCSS scheme.  \m {\command {Test MapCSS 0.2 generation}} will create \m {out/roentgen_mapcss} directory with simple MapCSS 0.2 scheme adding icons from Röntgen icon set to nodes and areas\: \m {.mapcss} file and directory with icons.

To create MapCSS with Röntgen style also for ways and relations, run \m {roentgen mapcss --ways}.

\options {mapcss}

\3 {Use Röntgen as JOSM map paint style}

\list
    {Run \m {\command {Test MapCSS 0.2 generation}}.}
    {Open \ref {https://josm.openstreetmap.de/} {JOSM}.}
    {Go to \kbd {Preferences} → Third tab on the left → \kbd {Map Paint Styles}.}
    {Active styles: press \kbd {+}.}
    {URL / File: set path to \m {out/roentgen_mapcss/roentgen.mapcss}.}

To enable / disable Röntgen map paint style go to \kbd {View} → \kbd {Map Paint Styles} → \kbd {Röntgen}.

\4 {Example}

\image {doc/josm.png} {JOSM example}

Example of using Röntgen icons on top of Mapnik style in JOSM.  Map Paint Styles look like\:
\list
    {✓ Mapnik (true)}
    {✓ Röntgen}