From ac3afadba547b4b9a4063da567acd6d2f4f74554 Mon Sep 17 00:00:00 2001
From: Daniel Schadt <kingdread@gmx.de>
Date: Wed, 18 Jan 2023 18:46:39 +0100
Subject: add support for SQLite output

---
 README.adoc | 38 ++++++++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 4 deletions(-)

(limited to 'README.adoc')

diff --git a/README.adoc b/README.adoc
index 8636e74..9c673d9 100644
--- a/README.adoc
+++ b/README.adoc
@@ -8,7 +8,7 @@ hittekaart - A GPX track heatmap generator.
 == SYNOPSIS
 
 ----
-hittekaart [--output=...] [--min-zoom=...] [--max-zoom=...] [--threads=...] FILES...
+hittekaart [--output=...] [--min-zoom=...] [--max-zoom=...] [--threads=...] [--sqlite] FILES...
 ----
 
 == INSTALLATION
@@ -38,6 +38,29 @@ 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.
 
+=== SQLITE OUTPUT
+
+In order to overcome storage overhead when saving many small files (see the tip
+and table further below), `hittekaart` can instead output a SQLite database
+with the heatmap tile data. To do so, use the `--sqlite` command line option,
+and control where the SQLite file should be placed with `--output`/`-o`.
+
+While this does not allow you to immediately serve the tiles with a HTTP
+server, it does cut down on the wasted space on non-optimal file systems.
+
+The generated SQLite file will have one table with the following schema:
+
+[source,sql]
+----
+CREATE TABLE tiles (
+    zoom INTEGER,
+    x INTEGER,
+    y INTEGER,
+    data BLOB,
+    PRIMARY KEY (zoom, x, y)
+);
+----
+
 === INPUT FILES
 
 `hittekaart` expects GPX track files with the `.gpx` extension. It will parse
@@ -140,8 +163,8 @@ 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.
+If you don't need the tiles in separate files, you can use the SQLite output
+mode. For the same data as above, the SQLite database would be 73 MiB in size.
 ====
 
 == OPTIONS
@@ -161,7 +184,14 @@ The following options are supported:
     will automatically pick a default.
 
 `-o DIRECTORY`, `--output=DIRECTORY`::
-    Generate the output tiles into the given directory. Defaults to `tiles/`.
+    Generate the output tiles into the given directory. Defaults to `tiles/`
+    when generating single files, and `tiles.sqlite` when storing the tiles in
+    a SQLite database.
+
+`--sqlite`::
+    Output a single SQLite file with all tiles instead of saving each tile as a
+    separate PNG file. In this case, `-o` can be used to set the location of
+    the SQLite database. The schema is described above.
 
 == EXAMPLE
 
-- 
cgit v1.2.3