From d5f8c6cb6e5156e1e6ee29cf9c86f58db5a540a7 Mon Sep 17 00:00:00 2001 From: Daniel Schadt Date: Tue, 7 Mar 2023 19:19:40 +0100 Subject: add some documentation about transformers --- doc/index.rst | 1 + doc/user.rst | 12 ++++++++++ doc/user/images/fixed_elevation.png | Bin 0 -> 8658 bytes doc/user/images/wrong_elevation.png | Bin 0 -> 7824 bytes doc/user/transformers.rst | 45 ++++++++++++++++++++++++++++++++++++ 5 files changed, 58 insertions(+) create mode 100644 doc/user.rst create mode 100644 doc/user/images/fixed_elevation.png create mode 100644 doc/user/images/wrong_elevation.png create mode 100644 doc/user/transformers.rst diff --git a/doc/index.rst b/doc/index.rst index 9ce95b9..0b69ef1 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,6 +12,7 @@ Welcome to Fietsboek's documentation! administration developer + user .. toctree:: :maxdepth: 1 diff --git a/doc/user.rst b/doc/user.rst new file mode 100644 index 0000000..ab210dc --- /dev/null +++ b/doc/user.rst @@ -0,0 +1,12 @@ +User Guide +========== + +.. toctree:: + :maxdepth: 2 + :caption: Contents + + user/transformers + +This is the user guide for Fietsboek! In here, you can find information that +might be interesting if you plan on sharing your tracks on a Fietsboek +instance. diff --git a/doc/user/images/fixed_elevation.png b/doc/user/images/fixed_elevation.png new file mode 100644 index 0000000..10d34c7 Binary files /dev/null and b/doc/user/images/fixed_elevation.png differ diff --git a/doc/user/images/wrong_elevation.png b/doc/user/images/wrong_elevation.png new file mode 100644 index 0000000..2e8557b Binary files /dev/null and b/doc/user/images/wrong_elevation.png differ 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. -- cgit v1.2.3