= 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] ----
---- == 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 .