add some documentation about transformers

1 files changed, 45 insertions, 0 deletions

diff --git a/doc/user/transformers.rst b/doc/user/transformers.rst
new file mode 100644
index 0000000..c8ddf01
--- /dev/null
+++ b/doc/user/transformers.rst
@@ -0,0 +1,45 @@
+Transformers
+============
+
+Transformers are small (or big) transformations that are applied to your GPX
+track after it has been uploaded. This allows Fietsboek to provide some common,
+simple editing options, without users having to do that themselves.
+
+All transformers are optional and disabled by default. You can enable
+transformers when uploading a track on the bottom of the page. You can also
+enable transformers for already uploaded tracks in the editing view.
+
+.. note::
+
+    When enabling transformers for already existing tracks, your browser might
+    not show the changed track. Try force-refreshing (Crtl + F5) the page so
+    that it reloads the GPX from the server.
+
+In other applications, transformers are sometimes called "filters". That term
+however has many different meanings (like the filters on the "Browse" page),
+and as such, Fietsboek calls them transformers.
+
+Fix Null Elevation
+------------------
+
+The *fix null elevation* transformer removes points at the start and end of a
+track that have a "wrong" elevation. This helps to avoid issues when GPX
+trackers don't have elevation data yet and fill in 0, leading to wrong uphill
+calculations and wrong diagrams:
+
+.. image:: images/wrong_elevation.png
+    :width: 200
+    :alt: An elevation graph that starts at 0 and makes a jump to 165.
+
+Activating the transformer will produce the following track:
+
+.. image:: images/fixed_elevation.png
+    :width: 200
+    :alt: The same track, but with a fixed elevation graph that starts at 165.
+
+The transformer considers "wrong" elevation to be either points that have an
+elevation of 0, or points that have a slope of more than 100% to the next
+point.
+
+To fix those points, the transformer will find the first correct point, and
+copy its elevation to the wrong points.