From 4b8e5478f523a1addecd0335866e8bffecffde1b Mon Sep 17 00:00:00 2001 From: Sergey Vartanov Date: Sat, 28 Aug 2021 16:27:48 +0300 Subject: [PATCH] Issue #69: add documentation. --- README.md | 40 ++++++++++++++++++++++----------------- doc/readme.moi | 18 ++++++++++++++---- roentgen/moire_manager.py | 2 +- roentgen/ui.py | 3 ++- 4 files changed, 40 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index c2c4b09..2855b84 100644 --- a/README.md +++ b/README.md @@ -153,13 +153,9 @@ will download OSM data to `cache/2.284,48.860,2.290,48.865.osm` and write output | `-o`, `--output` `` | output SVG file name, default value: `out/map.svg` | | `-b`, `--boundary-box` `,,,` | geo boundary box; if first value is negative, enclose the value with quotes and use space before `-` | | `--cache` `` | path for temporary OSM files, default value: `cache` | -| `--buildings` `` | building drawing mode: flat, isometric, isometric-no-parts, default value: `flat` | -| `--mode` `` | map drawing mode: normal, author, time, default value: `normal` | -| `--overlap` `` | how many pixels should be left around icons and text, default value: 12 | -| `--labels` `` | label drawing mode: no, main, all, default value: `main` | | `-s`, `--scale` `` | OSM zoom level, default value: 18 | -| `--level` | display only this floor level, default value: `overground` | -| `--seed` `` | seed for random | + ++ see [map configuration options](#map-options) Tile generation --------------- @@ -172,13 +168,9 @@ Command `tile` is used to generate PNG tiles for [slippy maps](https://wiki.open | `-t`, `--tile` `//` | tile specification | | `--cache` `` | path for temporary OSM files, default value: `cache` | | `-b`, `--boundary-box` `,,,` | construct the minimum amount of tiles that cover requested boundary box | -| `--buildings` `` | building drawing mode: flat, isometric, isometric-no-parts, default value: `flat` | -| `--mode` `` | map drawing mode: normal, author, time, default value: `normal` | -| `--overlap` `` | how many pixels should be left around icons and text, default value: 12 | -| `--labels` `` | label drawing mode: no, main, all, default value: `main` | -| `-s`, `--scale` `` | OSM zoom level, default value: 18 | -| `--level` | display only this floor level, default value: `overground` | -| `--seed` `` | seed for random | +| `-s`, `--scales` `` | OSM zoom levels; can be list of numbers or ranges, e.g. `16-18`, `16,17,18`, or `16,18-20`, default value: `18` | + ++ see [map configuration options](#map-options) ### Generate one tile ### @@ -193,10 +185,10 @@ or specify any geographical coordinates inside a tile: ```bash roentgen tile \ --coordinates , \ - --scale + --scales ``` -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. `--scale` option will be ignored if it is used with `--tile` option. +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. `--scales` option will be ignored if it is used with `--tile` option. Example: @@ -213,7 +205,7 @@ Specify boundary box to get the minimal set of tiles that covers the area: ```bash roentgen tile \ --boundary-box ,,, \ - --scale + --scales ``` 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 `out/tiles/tile___.svg` and PNG files `out/tiles/tile___.svg`, where `x` and `y` are tile coordinates. @@ -237,6 +229,20 @@ roentgen server Stop server interrupting process with Ctrl + C. +Map options +----------- + +Map configuration options used by `render` and `tile` commands: + +| Option | Description | +|---|---| +| `--buildings` `` | building drawing mode: flat, isometric, isometric-no-parts, default value: `flat` | +| `--mode` `` | map drawing mode: normal, author, time, default value: `normal` | +| `--overlap` `` | how many pixels should be left around icons and text, default value: 12 | +| `--labels` `` | label drawing mode: no, main, all, default value: `main` | +| `--level` | display only this floor level, default value: `overground` | +| `--seed` `` | seed for random | + MapCSS 0.2 generation --------------------- @@ -264,7 +270,7 @@ To enable / disable Röntgen map paint style go to View → Map ![JOSM example](doc/josm.png) -Example of using Röntgen icons on top of Mapnik style. Map Paint Styles: +Example of using Röntgen icons on top of Mapnik style in JOSM. Map Paint Styles look like: * ✓ Mapnik (true) * ✓ Röntgen diff --git a/doc/readme.moi b/doc/readme.moi index 338fd18..723294d 100644 --- a/doc/readme.moi +++ b/doc/readme.moi @@ -190,12 +190,16 @@ will download OSM data to \m {cache/2.284,48.860,2.290,48.865.osm} and write out \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\: @@ -206,9 +210,9 @@ or specify any geographical coordinates inside a tile\: \code {roentgen tile \\ --coordinates \formal {latitude},\formal {longitude} \\ - --scale \formal {OSM zoom level}} {bash} + --scales \formal {OSM zoom levels}} {bash} -Tile will be stored as SVG file \m {out/tiles/tile___.svg} and PNG file \m {out/tiles/tile___.svg}, where \m {x} and \m {y} are tile coordinates. \m {--scale} option will be ignored if it is used with \m {--tile} option. +Tile will be stored as SVG file \m {out/tiles/tile___.svg} and PNG file \m {out/tiles/tile___.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\: @@ -222,7 +226,7 @@ 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} \\ - --scale \formal {OSM zoom level}} {bash} + --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___.svg} and PNG files \m {out/tiles/tile___.svg}, where \m {x} and \m {y} are tile coordinates. @@ -240,6 +244,12 @@ Command \m {server} is used to run tile server for slippy maps. Stop server interrupting process with \kbd {Ctrl} + \kbd {C}. +\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. @@ -263,7 +273,7 @@ To enable / disable Röntgen map paint style go to \kbd {View} → \kbd {Map Pai \image {doc/josm.png} {JOSM example} -Example of using Röntgen icons on top of Mapnik style. Map Paint Styles\: +Example of using Röntgen icons on top of Mapnik style in JOSM. Map Paint Styles look like\: \list {✓ Mapnik (true)} {✓ Röntgen} diff --git a/roentgen/moire_manager.py b/roentgen/moire_manager.py index ca73df6..ba35a58 100644 --- a/roentgen/moire_manager.py +++ b/roentgen/moire_manager.py @@ -187,11 +187,11 @@ class RoentgenMoire(Default, ABC): command: str = self.clear(args[0]) if command == "render": ui.add_render_arguments(parser) - ui.add_map_arguments(parser) elif command == "server": ui.add_server_arguments(parser) elif command == "tile": ui.add_tile_arguments(parser) + elif command == "map": ui.add_map_arguments(parser) elif command == "element": ui.add_element_arguments(parser) diff --git a/roentgen/ui.py b/roentgen/ui.py index 14bcd8c..4d6f83e 100644 --- a/roentgen/ui.py +++ b/roentgen/ui.py @@ -119,7 +119,8 @@ def add_tile_arguments(parser: argparse.ArgumentParser) -> None: "--scales", type=str, metavar="", - help="OSM zoom level", + help="OSM zoom levels; can be list of numbers or ranges, e.g. `16-18`, " + "`16,17,18`, or `16,18-20`", default="18", )