From 18f99254e8a044cb1ebd8ea2653e13b67257b67b Mon Sep 17 00:00:00 2001
From: Daniel Schadt <kingdread@gmx.de>
Date: Sun, 15 Jan 2023 02:26:32 +0100
Subject: add README and LICENSE

---
 README.adoc | 230 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 230 insertions(+)
 create mode 100644 README.adoc

(limited to 'README.adoc')

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: '&copy; <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/>.
-- 
cgit v1.2.3

