diff options
Diffstat (limited to 'README.adoc')
| -rw-r--r-- | README.adoc | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..57a7759 --- /dev/null +++ b/README.adoc @@ -0,0 +1,230 @@ += hittekaart(1) +:source-highlighter: rouge + +== NAME + +hittekaart - A GPX track heatmap generator. + +== SYNOPSIS + +---- +hittekaart [--output=...] [--min-zoom=...] [--max-zoom=...] [--threads=...] FILES... +---- + +== INSTALLATION + +You can build the binary `./target/release/hittekaart` with `cargo`: + +---- +cargo build --release +---- + +== DESCRIPTION + +`hittekaart` is a tool to generate heatmaps from GPX tracks. It reads a number +of GPX files and produces OSM-compatible overlay tiles. Note that `hittekaart` +itself does not display any maps, instead you can use the generated heatmap +tiles as overlay layers in other applications such as +https://leafletjs.com/[Leaflet] or +https://sourceforge.net/projects/viking/[Viking]. + +=== OUTPUT FORMAT + +The generated tiles are saved according to the +https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames[slippy map tilenames], +so they can be served by any normal HTTP server. + +By default, the directory `tiles/` will be used as the root directory, so a +tile would be saved as `tiles/{zoom}/{x}/{y}.png`. You can change this by using +the `--output/-o` option. + +=== INPUT FILES + +`hittekaart` expects GPX track files with the `.gpx` extension. It will parse +them and read the track points. Optionally, you can feed it _compressed_ GPX +files: + +* Files ending with `.gz` will be considered `gzip` compressed and unpacked on + reading. +* Files ending with `.br` will be considered `brotli` compressed and unpacked + on reading. + +=== MULTITHREADING + +PNG compression takes up a big part of the heatmap generation. By default, +`hittekaart` will parallelize this process using a sensible default, using as +many threads as you have CPU cores. + +If you want to limit the number of threads that will be used, for example +because you want to run the heatmap generation in the background, use the +`--threads` option. Setting a thread count of 0 will use the default behaviour +of using all cores, while setting it to any other number will use that many +threads. + +=== ZOOM LEVELS + +By default, all zoom levels from 0 (a one-tile overview of the whole world) to +19 (the maximum that the openstreetmap.org tile server offers) will be +generated. However, you can control that setting with `--min-zoom` and +`--max-zoom`, for example if you don't want the heat maps to be as detailed. + +Keep in mind that every zoom level has four times as many tiles as the previous +zoom level, which quickly increases the number of tiles. This also means that +the more detailed levels will take up considerably more space than previous +levels. For example, a sample of 64 tracks leads to the following sizes: + +[%header,cols="1,1,1,1"] +|=== +|Level +|# Tiles +|Size +|Cum. Size + +|0 |1 |8.4 KiB |8.4 KiB + +|1 |1 |8.4 KiB |16.8 KiB + +|2 |1 |8.4 KiB |25.2 KiB + +|3 |1 |8.5 KiB |33.7 KiB + +|4 |1 |8.7 KiB |42.4 KiB + +|5 |2 |9.3 KiB |51.7 KiB + +|6 |2 |9.9 KiB |61.6 KiB + +|7 |2 |11 KiB |72.6 KiB + +|8 |2 |13 KiB |85.6 KiB + +|9 |3 |24 KiB |109.6 KiB + +|10 |7 |40 KiB |149.6 KiB + +|11 |23 |81 KiB |230.6 KiB + +|12 |60 |173 KiB |403.6 KiB + +|13 |160 |373 KiB |776.6 KiB + +|14 |402 |813 KiB |1589.6 KiB + +|15 |973 |1.8 MiB |3.4 MiB + +|16 |2,294 |3.9 MiB |7.3 MiB + +|17 |5,277 |8.1 MiB |15.4 MiB + +|18 |11,638 |16 MiB |31.4 MiB + +|19 |25,729 |34 MiB |65.4 MiB +|=== + +You can see that starting at level 14, each _single_ level takes as much space +as all previous levels combined. + +[TIP] +.A Note on Small Files +==== +The table shows the logical file sizes. Usually, the files are a bit bigger on +disk, as the file size is not an exact multiple of the block size. For a +standard block size of 4 KiB on an ext4 system for example, you would end up +with a total of 195 MiB, 107 MiB just for zoom level 19. This is a massive +increase in storage requirement, simply from the fact that the files do not +fill up all allocated blocks. + +If you intend to store a lot of heatmaps, it might be worth setting up a file +system that is optimized for a large amount of small files, for example by +setting a smaller block size. Many of the PNG images are smaller than 2 KiB +(half a standard block); for those 50% of storage is wasted already. + +Currently, `hittekaart` does not provide a built-in way to store or serve the +tiles more efficiently. +==== + +== OPTIONS + +The following options are supported: + +`--min-zoom=ZOOMLEVEL`:: + Set the minimum zoom level to generate. Defaults to 0, which is a one-tile + overview of the world. + +`--max-zoom=ZOOMLEVEL`:: + Set the maximum zoom level to generate (inclusive). Defaults to 19, the + maximum zoom that the openstreetmap.org tile server offers. + +`-t THREADS`, `--threads=THREADS`:: + Sets the number of threads. Defaults to 0, which means that `hittekaart` + will automatically pick a default. + +`-o DIRECTORY`, `--output=DIRECTORY`:: + Generate the output tiles into the given directory. Defaults to `tiles/`. + +== EXAMPLE + +You can generate a heatmap and serve it locally with the following commands: + +---- +hittekaart ~/Documents/GPX/*.gpx +cd tiles +python -m http.server +---- + +With the tile server running, you can then open a HTML file like the following: + +[source,html] +---- +<!DOCTYPE html> +<html> + <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.3/dist/leaflet.css" + integrity="sha256-kLaT2GOSpHechhsozzB+flnD+zUyjE2LlfWPgU04xyI=" + crossorigin=""/> + <script src="https://unpkg.com/leaflet@1.9.3/dist/leaflet.js" + integrity="sha256-WBkoXOwTeyKclOHuWtc+i2uENFpDZ9YPdf5Hf+D7ewM=" + crossorigin=""></script> + <style> +#map { height: 800px; } + </style> + <body> + <div id="map"></div> + <script> + var map = L.map('map').setView([52.520008, 13.404954], 13); + var osm = L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', { + maxZoom: 19, + attribution: '© <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>' + }); + var heatmap = L.tileLayer('http://localhost:8000/{z}/{x}/{y}.png', { + maxZoom: 19, + }); + + L.control.layers([osm], [heatmap]).addTo(map); + </script> + </body> +</html> +---- + +== BUGS + +Feel free you report bugs on the issue tracker at +https://gitlab.com/dunj3/hittekaart/-/issues or via email (see below). + +== AUTHOR + +Daniel Schadt - contact me electronically with my first name (in lowercase) at +kingdread.de + +== COPYRIGHT + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any later +version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with +this program. If not, see <https://www.gnu.org/licenses/>. |