map-machine/doc

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

\list
    {simple Python \href {http://openstreetmap.org} {OpenStreetMap} renderer (see \href {#usage} {usage}, \href {#map-generation} {renderer documentation}),}
    {\href {#icon-set} {set of icons},}
    {and \href {#map-styles} {map styles}.}

\href {https://travis-ci.org/enzet/Roentgen} {\image {https://travis-ci.org/enzet/Roentgen.svg?branch=master} {Build Status}}

The idea behind Röntgen project is 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 primarily created for OpenStreetMap contributors.  Suppose, you spent time adding colors for building walls, benches and shelters for bus stops but they are not represented on the standard tile layer.  Röntgen helps to display all changes you made.

Nevertheless, Röntgen map generator can generate precise but messy maps for OSM contributors as well as pretty and clean maps for OSM users.

\2 {Usage} {usage}

To get SVG map, just run

\code {python roentgen.py -b <lon1>,<lat1>,<lon2>,<lat2>} {bash}

(e.g. \tt {python roentgen.py -b 2.284,48.86,2.29,48.865}).  It will automatically download OSM data and write output map to \tt {map.svg}.  For more options see \href {#map-generation} {Map generation}.

\2 {Map features} {features}

\3 {Building levels} {levels}

Simple shapes for walls and shade in proportion to \osm {building:levels} value.

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

/*

\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 \href {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}

If tag is drawable it is displayed using icon combination and colors.  All icons are under \href {http://creativecommons.org/licenses/by/4.0/} {CC BY} license.  So, do whatever you want but give appropriate credit.  Icon set is heavily inspired by \href {https://github.com/mapbox/maki} {Maki},  \href {https://github.com/gmgeo/osmic} {Osmic}, and \href {https://github.com/ideditor/temaki} {Temaki} icon sets.

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

Draw icon grid\: \tt {python roentgen.py grid}.

\3 {Icon combination} {icon_combination}

Some icons can be combined into new icons.

\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']
\}} (\href {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']
\}} (\href {https://ideditor.github.io/location-conflation/?locationSet=%7Binclude%3A%20%5B%27jp%27%5D%7D&referrer=nsi} {view map})}
    }
    {
        {\tt {amenity=post_office}}
        {\icon {envelope} {-}}
        {\icon {japan_post} {-}}
    }
    {
        {\tt {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 {Map styles} {map-styles}

\3 {All tags style} {all_tags_style}

Options\: \tt {--show-missing-tags --overlap 0}.

Display as many OpenStreetMap data tags on the map as possible.

\3 {Pretty style} {pretty_style}

Options\: \tt {--draw-captions main --level overground}.

Display only not overlapping icons and main captions.

\3 {Creation time mode} {time_mode}

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

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

\3 {Author mode} {autor_mode}

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

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

\2 {Map generation} {map-generation}

\3 {Requirements} {requirements}

\list
    {Python (at least 3.8).}

\3 {Installation} {installation}

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

\3 {Script running} {script}

There are simple Python renderer that generates SVG map from OpenStreetMap data.  You can run it using\:

\code {python roentgen.py \\
    -b $\{LONGITUDE_1\},$\{LATITUDE_1\},$\{LONGITUDE_2\},$\{LATITUDE_2\} \\
    -o $\{OUTPUT_FILE_NAME\} \\
    -s $\{OSM_ZOOM_LEVEL\}} {bash}

Example\:

\code {python roentgen.py -b 2.284,48.86,2.29,48.865} {bash}

\3 {Main arguments} {arguments}

\4 {Required} {required_arguments}

\list
    {\tt {--boundary-box} or \tt {-b}\: boundary box to draw. Value\: \tt {<longitude 1>,<latitude 1>,<longitude 2>,<latitude 2>}.  Use space before first \tt {-} to escape negative values.}

\4 {Optional} {optional_arguments}

\list
    {\tt {--scale} or \tt {-s}\: OSM \href {https://wiki.openstreetmap.org/wiki/Zoom_levels} {zoom level}.  Default is 18.}
    {\tt {-o}\: path to output SVG file name.  Default is \tt {map.svg}.}
    {\tt {-i}\: path to input XML file name.  If this argument is not set, XML file will be downloaded through OpenStreetMap API.}

Check all arguments with \tt {python roentgen.py --help}.