From 6e0a86560d3f982e68cbe81cb0d30f2fe615bad5 Mon Sep 17 00:00:00 2001
From: Martin Ueding <mu@martin-ueding.de>
Date: Sat, 4 Jan 2025 12:37:06 +0100
Subject: [PATCH] Deployed 43a61eb with MkDocs version: 1.6.1

---
 reference/changelog/index.html |  34 +++++++++++++++++++++++
 search/search_index.json       |   2 +-
 sitemap.xml                    |  48 ++++++++++++++++-----------------
 sitemap.xml.gz                 | Bin 457 -> 457 bytes
 4 files changed, 59 insertions(+), 25 deletions(-)

diff --git a/reference/changelog/index.html b/reference/changelog/index.html
index ea25774..c430f42 100644
--- a/reference/changelog/index.html
+++ b/reference/changelog/index.html
@@ -866,6 +866,15 @@
     <nav class="md-nav" aria-label="Version 0">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#version-036" class="md-nav__link">
+    <span class="md-ellipsis">
+      Version 0.36
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#version-035" class="md-nav__link">
     <span class="md-ellipsis">
@@ -1798,6 +1807,15 @@
     <nav class="md-nav" aria-label="Version 0">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#version-036" class="md-nav__link">
+    <span class="md-ellipsis">
+      Version 0.36
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#version-035" class="md-nav__link">
     <span class="md-ellipsis">
@@ -2674,9 +2692,25 @@
 
 
 <h1 id="changelog">Changelog</h1>
+<!-- 
+- [GH-000](https://github.com/martin-ueding/geo-activity-playground/issues/000):
+-->
+
 <p>This is the log of high-level changes that I have done in the various versions.</p>
 <h2 id="version-0">Version 0</h2>
 <p>This is the pre-release series. Things haven't settled yet, so each minor version might introduce breaking changes.</p>
+<h3 id="version-036">Version 0.36</h3>
+<ul>
+<li><a href="https://github.com/martin-ueding/geo-activity-playground/issues/212">GH-212</a>: Add date filter to heatmap.</li>
+<li><a href="https://github.com/martin-ueding/geo-activity-playground/issues/209">GH-209</a>: Add square planner to navigation.</li>
+<li><a href="https://github.com/martin-ueding/geo-activity-playground/issues/211">GH-211</a>: Clip speed coloring with IQR to remove outliers.</li>
+</ul>
+<p>Internal stuff:</p>
+<ul>
+<li><a href="https://github.com/martin-ueding/geo-activity-playground/issues/206">GH-206</a>: Remove multiprocessing for parsing activities due to warnings about multithreading. This unfortunately slows down initial processing.</li>
+<li><a href="https://github.com/martin-ueding/geo-activity-playground/issues/214">GH-214</a>: Start to simplify the controller structure.</li>
+<li><a href="https://github.com/martin-ueding/geo-activity-playground/issues/213">GH-213</a>: Encode kinds via integers in heatmap to protect it against weird kind names containing control symbols.</li>
+</ul>
 <h3 id="version-035">Version 0.35</h3>
 <h4 id="version-0351">Version 0.35.1</h4>
 <ul>
diff --git a/search/search_index.json b/search/search_index.json
index 79a6c41..a410c33 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Geo Activity Playground","text":"<p>This is a software to view recorded outdoor activities and derive various insights from your data collection. All data is kept on your machine, hence it is suitable for people who have an affinity for data analysis and privacy.</p> <p>It caters to serve a similar purpose as Strava with Statshunters statshunters does but while not requiring you to share your location data with a service provider.</p> <p>One can use this program with a local collection of activity files (GPX, FIT, TCX, KML, CSV) or via the Strava API. The latter is appealing to people who want to keep their data with Strava primarily. In case that one wants to move, this might provide a noncommital way of testing out this project.</p> <p>The main user interface is web-based, you can run this on your Linux, Mac or Windows laptop. If you want, it can also run on a home server or your personal cloud instance.</p>"},{"location":"#screenshot-tour","title":"Screenshot tour","text":"<p>This is the view of a single activity:</p> <p></p> <p>You also get a beautiful interactive heatmap of all your activities:</p> <p></p> <p>Also there are plenty of summary statistics that lets you track how many rides, walks or hikes you have done:</p> <p></p> <p>If you're into explorer tiles or squadratinhos, this got you covered:</p> <p></p> <p>The configuration options are available within the interface such that you do not have to work with configuration files (like in earlier versions):</p> <p></p>"},{"location":"#get-started","title":"Get started","text":"<p>Install the software using one of the following options:</p> <ul> <li>Using the stable version on Linux</li> <li>Using the stable version on Windows</li> <li>Using the development version on Linux</li> </ul> <p>Get your activity data in place using one of the following options:</p> <ul> <li>Use local activity files if you already have these.</li> <li>Use the Strava API if you want to use this project to analyse your data on Strava.</li> <li>Move from Strava if you wan to leave Strava and work locally from then on.</li> </ul>"},{"location":"#free-software","title":"Free software","text":"<p>You can find the code on GitHub where you can also file issues. If you would like to use this yourself or contribute, feel free to reach out via the contact options from my website. I would especially appreciate improvements to the documentation. If you're familiar with Markdown and GitHub, you can also directly create a pull request. The code is licensed under the very permissive MIT license.</p>"},{"location":"acknowledgments/","title":"Acknowledgments","text":"<p>This project builds on many amazing other projects and would not be possible without them.</p>"},{"location":"acknowledgments/#bootstrap-css","title":"Bootstrap CSS","text":"<p>Writing CSS is not a trivial task. For many projects I have been using the Bootstrap CSS Framework which provides sensible default values, a 12-column grid system and a lot of components. Using this I didn't have to write any CSS myself and just attach a couple of classes to HTML elements.</p>"},{"location":"acknowledgments/#coloredlogs","title":"coloredlogs","text":"<p>Log messages in multiple colors are neat. Using the coloredlogs package we can get these super easily.</p>"},{"location":"acknowledgments/#fitdecode","title":"fitdecode","text":"<p>For reading FIT files I use the fitdecode library which completely handles all the parsing of this file format.</p>"},{"location":"acknowledgments/#flask","title":"Flask","text":"<p>The webserver is implemented with Flask which provides a really easy way to get started. It also ships with a development webserver which is enough for this project at the moment.</p>"},{"location":"acknowledgments/#geojson","title":"GeoJSON","text":"<p>Transferring geographic geometry data from the Python code to Leaflet is easiest with using the GeoJSON format. The official standard RFC is a bit hard to read, rather have a look at the Wikipedia article. And there is an online viewer that you can try out.</p>"},{"location":"acknowledgments/#github","title":"GitHub","text":"<p>For a smooth open source project one needs a place to share the code and collect issues. GitHub provides all of this for free.</p>"},{"location":"acknowledgments/#gpxpy","title":"gpxpy","text":"<p>For reading GPX files I use the gpxpy library. This allows me to read those files without having to fiddle with the underlying XML format.</p>"},{"location":"acknowledgments/#leaflet","title":"Leaflet","text":"<p>The interactive maps on the website are powered by Leaflet, a very easy to use JavaScript library for embedding interactive Open Street Map maps. It can also display GeoJSON geometries natively, of which I also make heavy use.</p>"},{"location":"acknowledgments/#mkdocs","title":"MkDocs","text":"<p>Writing documentation is more fun with a nice tool, therefore I use MkDocs together with Material for MkDocs. This powers this documentation.</p>"},{"location":"acknowledgments/#open-street-map","title":"Open Street Map","text":"<p>All the maps displayed use tiles from the amazing Open Street Map. This map is created by volunteers, the server hosting is for free. Without these maps this project would be quite boring.</p>"},{"location":"acknowledgments/#pandas","title":"Pandas","text":"<p>Working with thousands of activities, thousands of tiles and millions of points makes it necessary to have a good library for number crunching structured data. Pandas offers this and gives good performance and many features.</p>"},{"location":"acknowledgments/#parquet","title":"Parquet","text":"<p>I need to store the intermediate data frames that I generate with Pandas. Storing as JSON has disadvantages because dates are not properly encoded. Also it is a text format and quite verbose. The Parquet format is super fast and memory efficient.</p>"},{"location":"acknowledgments/#poetry","title":"Poetry","text":"<p>For managing all the Python package dependencies I use Poetry which makes it very easy to have all the Python project housekeeping with one tool.</p>"},{"location":"acknowledgments/#python","title":"Python","text":"<p>Almost all of the code here is written in Python, a very nice and versatile programming language with a vast ecosystem of packages.</p>"},{"location":"acknowledgments/#requests","title":"Requests","text":"<p>For doing HTTP requests I use the Requests library. It provides a really easy to use interface for GET and POST requests.</p>"},{"location":"acknowledgments/#scikit-learn","title":"Scikit-learn","text":"<p>Finding out which cluster is the largest one can either be formed as a graph search problem or as a data science problem. Using the Scikit-learn library I can easily use the DBSCAN algorithm to find the clusters of explorer tiles.</p>"},{"location":"acknowledgments/#statshunters","title":"Statshunters","text":"<p>The Statshunters page allows to import the activities from Strava and do analysis like explorer tiles, Eddington number and many other things. This has served as inspiration for this project.</p>"},{"location":"acknowledgments/#strava","title":"Strava","text":"<p>Although I have recorded some of my bike rides, I only really started to record all of them when I started to use Strava. This is a nice platform to track all activities. They also offer a social network feature, which I don't really use. They provide some analyses of the data, but they lack some analyses which I have now implemented in this project.</p>"},{"location":"acknowledgments/#stravalib","title":"stravalib","text":"<p>Strava has an API, and with stravalib there exists a nice Python wrapper. This makes it much easier to interface with Strava.</p>"},{"location":"acknowledgments/#strava-local-heatmap","title":"Strava local heatmap","text":"<p>https://github.com/remisalmon/Strava-local-heatmap</p>"},{"location":"acknowledgments/#tcxreader","title":"tcxreader","text":"<p>https://github.com/alenrajsp/tcxreader</p>"},{"location":"acknowledgments/#vega-altair","title":"Vega &amp; Altair","text":"<p>https://altair-viz.github.io/index.html https://vega.github.io/vega/</p>"},{"location":"acknowledgments/#velo-viewer","title":"Velo Viewer","text":""},{"location":"features/activity-view/","title":"Activity View","text":"<p>When you have selected a particular activity, you can view various details about it. This is what the screen looks like, we will go through the different parts in the following.</p> <p></p>"},{"location":"features/activity-view/#metadata","title":"Metadata","text":"<p>You have a column with metadata about the activity. The activity kind, whether it is a commute and the equipment are currently only supported via the Strava API, but we can build something to infer that from directories as well.</p> <p></p> <p>The calories are broken in the Strava API wrapper library that I use, therefore they don't show even if they are there.</p> <p>You can also see the ID which is an internal ID. When you use Strava API as a source, it will use the IDs that Strava gives. When you use files from a directory it will be computed from a hash of the path to the activity file.</p>"},{"location":"features/activity-view/#map-with-track","title":"Map with track","text":"<p>The interactive map shows a line with the activity. The speed is color-coded and peaks at 35 km/h with a yellow color.</p> <p></p>"},{"location":"features/activity-view/#distance-speed-and-altitude","title":"Distance, speed and altitude","text":"<p>Then there are a couple of time series plots. One is the distance vs. time. You can see how much distance you covered when and also see plateaus when you went on a break.</p> <p></p> <p>From this we can also compute the speed, although that might be pretty noisy:</p> <p></p> <p>And more interesting is the distribution of the various speed zones. This gives you an understanding how much time you spent at which speed. The buckets are set in 5 km/h intervals, but we could also change that.</p> <p></p> <p>If the time series data has the altitude, which isn't always the case, you can see it in the plot there. Here we can see how I did a tour and continually rode downhill. Except at the end where I had to climb in order to get the explorer tile that I wanted.</p> <p></p>"},{"location":"features/activity-view/#heart-rate","title":"Heart rate","text":"<p>The heart rate isn't too helpful, I feel. Still I've created the plot from the given data.</p> <p></p> <p>More interesting regarding the heart rate are the zones which one has spent time during this activity.</p> <p></p> <p>The definition of the heart rate zones is not standardized. Usually there are five zones and they have the same names. What differs is how their ranges are computed and there is some chaos around that.</p> <p>All definitions that I found take the maximum heart rate as the upper limit. One can measure this as part of a professional training or just use the 220 minus age prescription which at least for me matches close enough. What they differ on is how they use a lower bound. It seems that Polar or REI basically use 0 as the lower bound. My Garmin system also uses 0 as the lower bound. But as one can see in this blog, one can also use the resting heart rate as the lower bound.</p> <p>Based on the maximum and resting heart rate we will then compute the heart rate zones using certain percentages of effort. We can compute the heart rate as the following:</p> <p>rate = effort \u00d7 (maximum \u2013 minimum) + minimum</p> <p>The zones then take the following efforts:</p> Zone Effort Training 1 50 to 60 % Warmup/Recovery 2 60 to 70 % Base Fitness 3 70 to 80 % Aerobic Endurance 4 80 to 90 % Anerobic Capacity 5 90 to 100 % Speed Training <p>You can decide how you want to do work with that. If you want to have the same definitions that say Garmin uses, you need to just enter your birth year and we can compute the rest. If you want to use a lower bound, you need to specify that.</p>"},{"location":"features/calendar/","title":"Calendar","text":"<p>In order to access all the activities, there is a calendar view. It shows the years in rows and the months in columns. Each cell is a particular month and indicates the total distance traveled.</p> <p></p> <p>When you click on any of the months, you will see a calendar for a given month. Here is one of my months which doesn't show too personal data:</p> <p></p> <p>Clicking on an activity will lead you to the activity detail view.</p>"},{"location":"features/eddington/","title":"Eddington Number","text":"<p>The astronomer Sir Arthur Eddington like to go on longer bike rides. Apparently he did a lot of rides and had 84 days where he rode at least 84 miles. The Eddington number for cycling was coined from this.</p> <p>If you have an Eddington number E, it means that you have had E days with at least E kilometer distance. At the time of writing my number is 62, which means that I rode at least 62 km on 62 separate days. If I want to extend it to 63, I would need to have at least 63 km on 63 separate days. My bike rides that are just 62 km long will not count any more, making this challenge really hard.</p> <p>In the following plot you can see in blue the number of days that exceed the given distance. You can see that I have a 998 days that exceed 1 km, that's pretty easy when one just records enough data over many years. But then there are only 259 days where I exceed 20 km as this is beyond the distance that I have when I only go for a walk or run some simple errands.</p> <p></p> <p>The red curve indicates how many rides one needs to get the Eddington number. As it is a semi-log plot, the straight line is curved like a log-curve.</p> <p>You can see this cliff at around 80 km. That is the distance that I ride to work and back. I have many days with around 80 km, but longer rides are only on occasional bike trips. Therefore I think I will eventually make it to an Eddington number of 80, but beyond that will be super difficult.</p> <p>This is a life-long challenge, so who knows what happens in the future.</p>"},{"location":"features/eddington/#length-unit","title":"Length unit","text":"<p>The definition of the Eddington number depends on the length unit that one has. Eddington as a British person used the English mile as a base unit. Therefore his number of 84 is actually harder to achieve than a 84 based on kilometers because he needed to exceed 135 km (84 mi) on each ride.</p> <p>Therefore using a different length unit as a base changes the meaning. The kilometer is easier, the mile (1609.344 m) is harder. One could also use nautical miles (1852 m). And while we are at arbitrary unit systems, we could also use furlongs (201.168 m).</p>"},{"location":"features/equipment/","title":"Equipment Overview","text":"<p>When activities are tagged with the used equipment, one can tally the total distance traveled with each thing. This given as a table with the recently used equipment at the top:</p> <p></p> <p>And for each thing there is also a graph which shows how the distance accumulates over time:</p> <p></p> <p>Here one can see how with my old bike I only recorded the occasional bike trip and not nearly the 4000 km/a which I was doing. And then it got stolen in 2019, so I bought a new bike.</p> <p>This metadata is downloaded via the Strava API, for the directory source it is not yet supported. I thought about using directories like <code>Activities/{Activity Kind}/{Equipment Name}/{Activity Name}.gpx</code>. to indicate the kind and equipment. If you're interested in implementing this, let me know.</p>"},{"location":"features/explorer-tiles/","title":"Explorer Tiles","text":"<p>Maps accessible via the web browser are usually served as little image tiles. The Open Street Map uses the Web Mercator coordinate system to map from latitude and longitude to pixels on the map.</p> <p>Each tile is 256\u00d7256 pixels in size. The zoom levels zoom in by a factor of two. Therefore all the tiles are organized in a quad tree. As you zoom in, each tile gets split into four tiles which can then show more detail. The following prescription maps from latitude and longitude (given in degrees) to tile indices:</p> <pre><code>def compute_tile(lat: float, lon: float, zoom: int = 14) -&gt; tuple[int, int]:\n    x = np.radians(lon)\n    y = np.arcsinh(np.tan(np.radians(lat)))\n    x = (1 + x / np.pi) / 2\n    y = (1 - y / np.pi) / 2\n    n = 2**zoom\n    return int(x * n), int(y * n)\n</code></pre> <p>At zoom level 14 the tiles have a side length of roughly 1.5 km in Germany. These tiles are used as the basis for explorer tiles. The basic idea is that every tile where you have at least one point in an activity is considered an explored tile.</p> <p>From your activities the program will extract all the tiles that you have visited. And then it does a few things with those. One main thing is that it will display these on an interactive map. When we zoom into one area where I've been on vacation in 2023, you can see the explored tiles there:</p> <p></p> <p>The filled tiles are explored, I have been there. The colored tiles are cluster tiles, that means that all their four neighbor tiles are also explored.</p> <p>You can see here how I have explored a region and ensured that it is mostly contiguous.</p> <p>There is another vacation from 2013 where I wasn't aware of the cluster tiles. I just did some bike trips and didn't look out for the tiles. There the tiles look like this:</p> <p></p> <p>You see all these gaps in there. Also there are three different clusters which are not connected. Each unique cluster is assigned a different color such that one can see where there are gaps between the cluster tiles. And filling the gaps is what the explorer tiles are about: This OCD (obsessive compulsive disorder) like craving to fill in the gaps.</p> <p>Let's take a look at my main cluster of explorer tiles. Here I have explored much more than in the areas where I was on vacation.</p> <p></p> <p>You can see an additional feature, the blue square. This is the one largest square which can be fit into all explored tiles. In this picture it has size 21\u00b2. The idea of the square is to have a really tough challenge. Not only does one need to explore increasingly many tiles to expand the square by one unit, there must not be any gaps.</p> <p>As you can see in this picture, there is a tile missing right at the top edge. I will never be able to get that because that is an off-limits area of the German air force at the airport. So I can expand my square to the south only.</p> <p>You can click on each tile and get some information about that particular tile. You can see when you first explored that and with which activity. Also it shows the last activity there as well as the number of activities. If it is a local cluster, it will also show the cluster size.</p> <p></p> <p>There is also the option to color the tiles by first or last visit. Use one of the buttons above the map:</p> <p></p> <p>Then the map will show the first visit:</p> <p></p> <p>Or how recent your last visit is:</p> <p></p> <p>This uses Matplotlib's Plasma scale (see below) to color the age of a tile. Very new tiles will get a yellow color, a year old tiles a reddish color and tiles two years old or older a colder blue. This is the scale:</p> <p></p> <p>You can switch this with the buttons above the map.</p>"},{"location":"features/explorer-tiles/#squadratinhos","title":"Squadratinhos","text":"<p>The explorer tiles at zoom level 14 are best suited for cycling and to discover the area around the city. There is a derived definition, the squadratinhos which are defined at zoom level 17 and therefore a factor 8 smaller in each direction. Each explorer tile is therefore divided into 256 squadratinhos.</p> <p>These are better suited for walking and making sure that you really explored every little place in your neighborhood. Since they are so small, there are many properties which one cannot go onto, like industrial sites, airports or just a wide river.</p> <p>For my home city it looks like this:</p> <p></p> <p>You can see how the squadratinhos are much smaller than the explorer tiles and how they lend themselves to more local exploring.</p>"},{"location":"features/explorer-tiles/#history","title":"History","text":"<p>The map only shows the current state of your explorer tiles. In order to get a sense of how many new tiles you have discovered in the past, there are also plots that show you how you have extended the total number of squares, the size of your largest cluster and the size of your largest square over time:</p> <p></p>"},{"location":"features/explorer-tiles/#missing-tile-files","title":"Missing tile files","text":"<p>Looking at these maps you can see the gaps. And if you feel challenged to fill those, you might want to plan a \u201ctactical bike ride\u201d to explore those. Let us take another look at my tile history in Sint Annaland:</p> <p></p> <p>You can see those gaps in the clusters. To make it easier to explore tiles while on the go, we can export a file with the missing tiles. Pan and zoom the map to an area which you want to export. Below the map you will find two links:</p> <p>Download missing tiles in visible area as GeoJSON or GPX.</p> <p>This export is available as GeoJSON or GPX such that you can open it with other applications. For instance with GPX See on Linux it looks like this when opening the GeoJSON file:</p> <p></p> <p>You can then upload the GeoJSON file to Bikerouter and it will display there:</p> <p></p> <p>Then plan a route that goes through as many tiles as possible. Download the route as GPX and use an app like OsmAnd to ride along it.</p>"},{"location":"features/explorer-tiles/#missing-tiles-on-the-go","title":"Missing tiles on the go","text":"<p>The above is nice to plan the route, perhaps you also want to take the missing tiles along to do spontaneous tile hunting.</p> <p>A possibility should be Organic Maps which is a FOSS app that can display offline maps and also show GPX files.</p> <p>Another method is to use Open Street Map uMap, either the one hosted in Germany or France. Then you can create a new personal map (consider limiting the access rights, default is public) and upload the GeoJSON file. Then you can use that map on the code to see your position and the missing tiles:</p> <p></p> <p>Yet another option is Offline Maps. That is able to display GeoJSON on Android, though one needs to buy the add-on for like 5 EUR.</p> <p>On Android one can use the OsmAnd app to display tracks and also try to visualize the missing tiles. Unfortunately GeoJSON is not supported, therefore one has to play some tricks. The missing tiles are also exported as a GPX file with a track for each missing tile. This looks strange, but it is a bit helpful with OsmAnd. This is how the file looks like in GPXSee:</p> <p></p> <p>And on OsmAnd such files look like this:</p> <p></p> <p>Unfortunately OsmAnd becomes a very sluggish with such a huge track imported, so make sure to only export it from rather small regions.</p>"},{"location":"features/explorer-tiles/#square-planner","title":"Square planner","text":"<p>From the explorer tile views you can open the square planner which allows you to see which tiles you need to explore in order to extend the square into a particular direction. The screen will open with the largest square that you have, then you can use the buttons to extend or move your square.</p> <p></p> <p>Using the buttons in the middle you can move the square, the buttons in the corners allow to extend or shrink the square.</p> <p>When you have selected the square that you want to target, you can download the missing files in for that square as GeoJSON or GPX.</p>"},{"location":"features/heatmaps/","title":"Heatmaps","text":"<p>A heatmap shows where you have been more often than other places. There is an interactive and zoomable heatmap that looks like this:</p> <p></p> <p>Here you can see where I mostly travel between Bonn and Cologne.</p> <p>You have the option to download a rendered heatmap from the current viewport of the interactive map as in image with up to 4000\u00d74000 pixels, there is a link below the map.</p>"},{"location":"features/kind-rename/","title":"Kind rename","text":"<p>Metadata and importing from several sources can be messy and in some cases Strava will export its acivity types/activity kinds under names like root='Ride' and not \"Ride\". That can lead to issues with tagging and the heatmap - in this case we have multiple, overlapping activity kinds for the same activity kinds.</p> <p>To fix this, go to Admin -&gt; Settings -&gt; Kind rename</p> <ul> <li>Type in the box to define how you want to reprocess your activities</li> <li>The Format is <code>Existing name =&gt; New name</code></li> <li>f.e. to rename <code>root='Ride'</code> to <code>'Ride'</code> put in <code>root='Ride' =&gt; Ride</code></li> <li>Click on \"Save\", the system will then reprocess all affected activities</li> <li>This can take a few minutes depending on the amount of activities</li> </ul>"},{"location":"features/overview/","title":"Overview page","text":"<p>When you start the webserver, you will see the overview page. It looks like the following and shows the activities you've done in the past 30 days:</p> <p></p> <p>Then below that you see the latest 15 activities with their tracks on interactive maps.</p> <p></p> <p>Each card contains the name, activity type, distance and duration. The non-commute activities are highlighted with a blue border, the commutes just have a gray border.</p> <p>Click on any of the names and you will see the details of that activity.</p>"},{"location":"features/share-picture/","title":"Share Picture","text":"<p>On each activity page you will find a \"share picture\" like the following:</p> <p></p>"},{"location":"features/share-picture/#privacy-zones","title":"Privacy zones","text":"<p>You might want to remove points that are close to your home, work or relatives. For this you can define arbitrary polygons as \"privacy zones\".</p> <p>To create such a polygon, go to GeoJSON.io. You will see a map similar to this one:</p> <p></p> <p>Select the polygon tool and click on the map to span the polygon.</p> <p></p> <p>Once you are done, press Enter to finish the polygon. In the left panel the GeoJSON output will appear:</p> <p></p> <p>For this case, we have this GeoJSON:</p> <pre><code>{\n  \"type\": \"FeatureCollection\",\n  \"features\": [\n    {\n      \"type\": \"Feature\",\n      \"properties\": {},\n      \"geometry\": {\n        \"coordinates\": [\n          [\n            [\n              6.87987514009842,\n              50.68272071401333\n            ],\n            [\n              6.878628929151887,\n              50.6819310903943\n            ],\n            [\n              6.8780142440226655,\n              50.68125883278765\n            ],\n            [\n              6.879563587362242,\n              50.68022375065988\n            ],\n            [\n              6.880599289703014,\n              50.68029311254671\n            ],\n            [\n              6.8814665851591315,\n              50.68102940933676\n            ],\n            [\n              6.881542368256589,\n              50.681723011688035\n            ],\n            [\n              6.8812729172415175,\n              50.682176515374465\n            ],\n            [\n              6.87987514009842,\n              50.68272071401333\n            ]\n          ]\n        ],\n        \"type\": \"Polygon\"\n      }\n    }\n  ]\n}\n</code></pre> <p>Paste this in the appropriate settings menu.</p> <p>You can name the zone to help you remember what it encompasses. You can add multiple zones.</p> <p>Points that are within any of the privacy zones will not be shown in the share pictures. Except when all of the points are in the privacy zone, then all the points will be shown.</p>"},{"location":"features/upload/","title":"Uploading activities","text":"<p>Some users don't want to restart the application each time they add new activities but run it on their home server. For this use case you can upload activities. Uploading files is a potential security issue and it is protected with a password. This feature is only enabled when you have set a password in the configuration file.</p> <p>Put the following into your <code>config.json</code> file:</p> <pre><code>{\n    \"upload_password\": \"fb1c8d62-07a5-47bf-ada1-30aa66e41d8a\"\n}\n</code></pre> <p>Be sure to choose your own password and not use the one from this documentation.</p> <p>Then you can go to the upload page and see this form:</p> <p></p> <p>Select a file that you want to upload and a target directory within the \u201cActivities\u201d directory. Finally, enter the password from the configuration file.</p> <p>After you have uploaded the file, you will be redirected to the parsed activity.</p>"},{"location":"getting-started/advanced-metadata-extraction/","title":"Advanced Metadata extraction","text":"<p>If you would like to set the metadata fields or change what part of the filename should be the activity name, you can use a custom directory structure with corresponding regular expressions.</p> <p>An example directory structure:</p> <pre><code>Activities/\n\u251c\u2500 Ride/\n\u2502  \u251c\u2500 Trekking Bike/\n\u2502  \u2502  \u251c\u2500 2024-03-03-17-42-10 Home to Bakery.gpx\n\u251c\u2500 Hike/\n\u2502  \u251c\u2500 Hiking Boots 2019/\n\u2502  \u2502  \u251c\u2500 2024-03-03-11-03-18 Some nice place with Alice and Bob.fit\n</code></pre>"},{"location":"getting-started/advanced-metadata-extraction/#custom-regular-expressions","title":"Custom Regular expressions","text":"<p>The program uses regular expressions to search for patterns in the relative path (in Activities) and extracts the relevant parts with named capture groups <code>(?P&lt;kind&gt;)</code>, <code>(?P&lt;equipment&gt;)</code>, <code>(?P&lt;name&gt;)</code>.</p> <p>You can use python to test your regular expressions. Read the python re documentation for help.</p> <p><pre><code>import re\nre.search(r'(?P&lt;kind&gt;[^/]+)/(?P&lt;equipment&gt;[^/]+)/(?P&lt;name&gt;[^/.]+)', '/Ride/Trekking Bike/2024-03-03-17-42-10 Home to Bakery.gpx').groupdict()\n</code></pre> <pre><code>{'kind': 'Ride', 'equipment': 'Trekking Bike', 'name': '2024-03-03-17-42-10 Home to Bakery'}\n</code></pre></p> <p>You can add your custom regular expressions under the <code>Admin</code> menu - <code>Settings</code> - <code>Metadata Extraction</code> in the WebUI. Settings are saved in your <code>Playground</code> directory.</p>"},{"location":"getting-started/advanced-metadata-extraction/#filename-as-name-simple","title":"Filename as Name (simple)","text":"<p>Path:</p> <pre><code>Activities/\n\u251c\u2500 Ride/\n\u2502  \u251c\u2500 Trekking Bike/\n\u2502  \u2502  \u251c\u2500 2024-03-03-17-42-10 Home to Bakery.gpx\n</code></pre> <pre><code>(?P&lt;kind&gt;[^/]+)/(?P&lt;equipment&gt;[^/]+)/(?P&lt;name&gt;[^/.]+)\n</code></pre> <ul> <li>kind: <code>Ride</code></li> <li>equipment: <code>Trekking Bike</code></li> <li>name: <code>2024-03-03-17-42-10 Home to Bakery</code></li> </ul>"},{"location":"getting-started/advanced-metadata-extraction/#filename-without-date-as-name-useful-for-osmand-naming","title":"Filename without date as Name (useful for OsmAnd naming)","text":"<p>Path:</p> <pre><code>Activities/\n\u251c\u2500 Ride/\n\u2502  \u251c\u2500 Trekking Bike/\n\u2502  \u2502  \u251c\u2500 2024-03-03-17-42-10 Home to Bakery.gpx\n\u2502  \u2502  \u251c\u2500 2024-03-04-16-52-26.gpx\n\u2502  \u2502  \u251c\u2500 2024-04-21_10-28_Sun OsmAnd default track.gpx\n\u2502  \u2502  \u251c\u2500 2024-04-22_07-55_Mon.gpx\n</code></pre> <pre><code>(?P&lt;kind&gt;[^/]+)/(?P&lt;equipment&gt;[^/]+)/[-\\d_ ]+(?P&lt;name&gt;[^/]+)(?:\\.\\w+)+$\n</code></pre> <ul> <li>kind: <code>Ride</code></li> <li>equipment: <code>Trekking Bike</code></li> <li>names: <code>Home to Bakery</code> ; <code></code> ; <code>Sun OsmAnd default track</code> ; <code>Mon</code></li> </ul> <p>Attention, name may be empty if it is not included in the file name. For OsmAnd default naming the weekday is included in the name.</p>"},{"location":"getting-started/advanced-metadata-extraction/#filename-after-first-space-as-name","title":"Filename after first space as Name","text":"<p>Path:</p> <pre><code>Activities/\n\u251c\u2500 Ride/\n\u2502  \u251c\u2500 Trekking Bike/\n\u2502  \u2502  \u251c\u2500 2024-03-03-17-42-10 Home to Bakery.gpx\n\u2502  \u2502  \u251c\u2500 2024-04-22_07-55_Mon.gpx\n\u2502  \u2502  \u251c\u2500 2024-04-21_10-28_Sun OsmAnd default track.gpx\n</code></pre> <pre><code>(?P&lt;kind&gt;[^/]+)/(?P&lt;equipment&gt;[^/]+)/\\S+ ?(?P&lt;name&gt;[^/\\.]*)\n</code></pre> <ul> <li>kind: <code>Ride</code></li> <li>equipment: <code>Trekking Bike</code></li> <li>names: <code>Home to Bakery</code> ; <code></code> ; <code>OsmAnd default track</code></li> </ul> <p>Attention, name may be empty if it is not included in the file name (also for OsmAnd default naming).</p>"},{"location":"getting-started/advanced-metadata-extraction/#grouping-activity-files-under-a-common-name-for-example-all-your-commutes","title":"Grouping activity files under a common name, for example all your commutes","text":"<p>Path:</p> <pre><code>Activities/\n\u251c\u2500 Ride/\n\u2502  \u251c\u2500 Trekking Bike/\n\u2502  \u2502  \u251c\u2500 Commute/\n\u2502  \u2502  \u2502  \u251c\u2500 2024-03-04-07-06-12.gpx\n\u2502  \u2502  \u2502  \u251c\u2500 2024-03-04-15-42-32.gpx\n</code></pre> <pre><code>(?P&lt;kind&gt;[^/]+)/(?P&lt;equipment&gt;[^/]+)/(?P&lt;name&gt;[^/]+)/\n</code></pre> <ul> <li>kind: <code>Ride</code></li> <li>equipment: <code>Trekking Bike</code></li> <li>name: <code>Commute</code> (for all activities in Commute directory )</li> </ul>"},{"location":"getting-started/advanced-metadata-extraction/#activities-without-equipment","title":"Activities without equipment","text":"<p>Path:</p> <pre><code>Activities/\n\u251c\u2500 Run/\n\u2502  \u251c\u2500 2024-03-09-09-24-03 To the lake.gpx\n\u2502  \u251c\u2500 2024-03-10-09-44-37 To the top of the hill.gpx\n</code></pre> <pre><code>(?P&lt;kind&gt;[^/]+)/[-\\d_ ]+(?P&lt;name&gt;[^/]+)(?:\\.\\w+)+$\n</code></pre> <ul> <li>kind: <code>Run</code></li> <li>equipment: <code>Unknown</code></li> <li>names: <code>To the lake</code> ; <code>To the top of the hill</code></li> </ul>"},{"location":"getting-started/advanced-metadata-extraction/#next-steps","title":"Next Steps","text":"<p>If you you manually rename, move or delete your activity files, the program needs to reload to respect these changes. You can restart the program or visit <code>Scan New Activities</code> in the admin menu of the WebUI.</p>"},{"location":"getting-started/docker-compose-tailscale/","title":"Using Git Version via Docker Compose and Tailscale VPN","text":"<p>Docker is a software that allows you to run Linux programs in a container. Docker Compose is a tool for defining multi-container Docker environments in a single YAML configuration file and deploy it with a single command.</p> <p>Tailscale is a VPN solution based on the Wireguard protocol which lets you connect all devices within your virtual private network (tailnet). The Tailscale Docker container exposes the services only via a direct VPN connection, which avoids exposing ports to the open internet to connect to your geo-activity-playground instance on-the-go. It provides a domain with a valid Let's Encrypt certificate which is only accessible via the tailnet. The configuration is based on Docker Tailscale Guide.</p> <p>This how-to will give you an example <code>compose.yml</code> that can build the geo-activity-playground docker image from Github and start this project within a Docker container and connecting it via Tailscale.</p>"},{"location":"getting-started/docker-compose-tailscale/#tailscale-prerequisites","title":"Tailscale Prerequisites","text":"<ul> <li>Active account</li> <li>Enabled MagicDNS (in DNS section of admin console)</li> <li>Enabled HTTPS (in DNS section of admin console)</li> <li>Auth-Key</li> <li>ACL policy for tag</li> </ul>"},{"location":"getting-started/docker-compose-tailscale/#create-auth-key-and-acl-policy-for-tag","title":"Create Auth-Key and ACL policy for tag","text":"<p>More information on generating auth keys Navigate to https://login.tailscale.com/admin/settings/keys and generate an auth key.</p> <p>Example Auth-Key configuration: - Description: docker - Reusable: yes - Expiration: 7 days - Ephemeral: No - Tags: tag:container</p> <p>In order to use the tag, it must first be defined in your Access control policy in the admin console. Set the same tag as in the Auth-Key.</p> <pre><code>\"tagOwners\": {\n    \"tag:container\": [\"autogroup:admin\"],\n},\n</code></pre> <p>When you apply a tag to a device for the first time and authenticate it, the tagged device's key expiry is disabled by default.</p>"},{"location":"getting-started/docker-compose-tailscale/#preparing-tailscale-configuration","title":"Preparing Tailscale configuration","text":"<p>The geo-activity-playground service will be made available by using the Tailscale Serve functionality. It routes traffic from other devices on your Tailscale network (known as a tailnet) to a local service, in this case inside the container. It creates a reverse proxy to the geo-activity-playground container internal port 5000 (do not change it). <code>TS_CERT_DOMAIN</code> is comprised of a subdomain (hostname set in the <code>compose.yml</code>) and the tailnet root domain.</p> <pre><code>mkdir -p /docker/geo-activity-playground/{ts-state,ts-config}\ncd /docker/geo-activity-playground/ts-config\nnano geo-activity-playground.json\n</code></pre> <pre><code>{\n  \"TCP\": {\n    \"443\": {\n      \"HTTPS\": true\n    }\n  },\n  \"Web\": {\n    \"${TS_CERT_DOMAIN}:443\": {\n      \"Handlers\": {\n        \"/\": {\n          \"Proxy\": \"http://127.0.0.1:5000\"\n        }\n      }\n    }\n  }\n}\n</code></pre>"},{"location":"getting-started/docker-compose-tailscale/#compose-configuration-with-tailscale-network","title":"Compose configuration with Tailscale network","text":"<p>With these steps the playground folder (which contains the activities) will be located in the docker project folder. The location can be changed in the <code>compose.yml</code>.</p> <pre><code>mkdir -p /docker/geo-activity-playground/playground/Activities\ncd /docker/geo-activity-playground\nnano compose.yml\n</code></pre> <pre><code>services:\n  ts-geo-activity-playground:\n    image: tailscale/tailscale:latest\n    container_name: ts-geo-activity-playground\n    hostname: geo-activity-playground # set your desired name, which will be the tailscale subdomain\n    environment:\n      - TS_AUTHKEY=tskey-auth-yyyyyyyyyyyyyyyyyyyyyyyyyyyy # paste your created Auth-Key\n      - TS_EXTRA_ARGS=--advertise-tags=tag:container # set the same tag as in the Auth-Key\n      - TS_SERVE_CONFIG=/config/geo-activity-playground.json\n      - TS_STATE_DIR=/var/lib/tailscale\n    volumes:\n      - /docker/geo-activity-playground/ts-state:/var/lib/tailscale\n      - /docker/geo-activity-playground/ts-config:/config\n      - /dev/net/tun:/dev/net/tun\n    cap_add:\n      - net_admin\n      - sys_module\n    restart: unless-stopped\n  geo-activity:\n    build:\n      context: https://github.com/martin-ueding/geo-activity-playground.git\n      # this sets the build context to the DOCKERFILE located in the Github repository\n    container_name: geo-activity-playground\n    depends_on:\n      - ts-geo-activity-playground # start container after the VPN network is active\n    network_mode: service:ts-geo-activity-playground # link container network to tailscale container\n    volumes:\n      - /docker/geo-activity-playground/playground:/data # optional: change left side to your desired playground directory\n    restart: unless-stopped\n</code></pre> <p>If you want to build the release version of geo-activity-playground from Github instead, you can adjust the build context and add the release tag. <code>context: https://github.com/martin-ueding/geo-activity-playground.git#0.29.1</code></p>"},{"location":"getting-started/docker-compose-tailscale/#building-image-and-running-container","title":"Building image and running container","text":"<p>You need to set up your files according to one of the presented methods, like activity files or the Strava API. Consult the other pages in the sidebar for the details.</p> <p>Once you have your playground directory, you can build the image and start the container.</p> <pre><code>docker compose build\ndocker compose up -d\n</code></pre> <p>This will start the webserver and expose it via your tailnet on <code>https://[HOSTNAME].[YourTailnetName].ts.net/</code>, eg. <code>https://geo-activity-playground.tail41a3.ts.net/</code>. In order to access your instance via that domain, you have to install and authenticate the Tailscale client app on your device you want to open it from.</p>"},{"location":"getting-started/docker-compose-tailscale/#updating-the-image","title":"Updating the image","text":"<p>If using the tagged release version of geo-activity-playground, update the tag to the latest one first.</p> <pre><code>docker compose down\ndocker compose build\ndocker compose up -d --force-recreate\n</code></pre>"},{"location":"getting-started/docker-compose/","title":"Using Git Version via Docker Compose","text":"<p>Docker is a software that allows you to run Linux programs in a container. Docker Compose is a tool for defining multi-container Docker environments in a single YAML configuration file and deploy it with a single command.</p> <p>This how-to will give you an example <code>compose.yml</code> that can build the geo-activity-playground docker image from Github and start this project within a Docker container.</p>"},{"location":"getting-started/docker-compose/#creating-directory-structure-and-composeyml","title":"Creating directory structure and compose.yml","text":"<p>With these steps the playground folder (which contains the activities) will be located in the docker project folder. The location can be changed in the <code>compose.yml</code>.</p> <pre><code>mkdir -p /docker/geo-activity-playground/playground/Activities\ncd /docker/geo-activity-playground\nnano compose.yml\n</code></pre> <pre><code>services:\n  geo-activity:\n    build:\n      context: https://github.com/martin-ueding/geo-activity-playground.git\n      # this sets the build context to the DOCKERFILE located in the Github repository\n    container_name: geo-activity-playground\n    volumes:\n      - /docker/geo-activity-playground/playground:/data  # optional: change left side to your desired playground directory\n    ports:\n      - 5000:5000 # optional: change the exposed port on the left side\n    restart: unless-stopped\n</code></pre> <p>If you want to build the release version from Github instead, you can adjust the build context and add the release tag. <code>context: https://github.com/martin-ueding/geo-activity-playground.git#0.29.1</code></p>"},{"location":"getting-started/docker-compose/#building-image-and-running-container","title":"Building image and running container","text":"<p>You need to set up your files according to one of the presented methods, like activity files or the Strava API. Consult the other pages in the sidebar for the details.</p> <p>Once you have your playground directory, you can build the image and start the container.</p> <pre><code>docker compose build\ndocker compose up -d\n</code></pre> <p>This will start the webserver on http://localhost:5000/ or at the port you chose to expose.</p> <p>Note that port 5000 may not be available on macOS because of AirPlay, so you can map to another port.</p>"},{"location":"getting-started/docker-compose/#updating-the-image","title":"Updating the image","text":"<p>If using the tagged release version, update the tag to the latest one first.</p> <pre><code>docker compose down\ndocker compose build\ndocker compose up -d --force-recreate\n</code></pre>"},{"location":"getting-started/docker/","title":"Using Git Version via Docker","text":"<p>Docker is a software that allows you to run Linux programs in a container. This how-to will show you how to build and start this project within a Docker container.</p>"},{"location":"getting-started/docker/#build-the-image","title":"Build the image","text":"<p>First you need to build the Docker image. For this download the source code and build the image using the following commands:</p> <pre><code>git clone https://github.com/martin-ueding/geo-activity-playground.git\ncd geo-activity-playground\nsudo docker build -t geo-activity-playground .\n</code></pre> <p>Perhaps you do not need <code>sudo</code> on your system.</p>"},{"location":"getting-started/docker/#run-the-image","title":"Run the image","text":"<p>You need to set up your files according to one of the presented methods, like activity files or the Strava API. Consult the other pages in the sidebar for the details.</p> <p>Once you have your playground directory, you can launch the Docker image with the following. Be sure to replace <code>path/to/playground</code> with your path.</p> <pre><code>sudo docker run -p 5000:5000 -v path/to/playground:/data -it geo-activity-playground\n</code></pre> <p>This will start the webserver on http://localhost:5000/.</p> <p>Note that port 5000 may not be available on macOS because of AirPlay, so you can map to another port by replacing the port specifier from above with <code>-p 8000:5000</code>. Then you can open http://localhost:8000/ in your browser.</p>"},{"location":"getting-started/installing-git-on-linux/","title":"Installing Git Version On Linux","text":"<p>As this project is still in development, you might want to have a peek into the development version. This is more advanced than using the stable versions, but not impossibly hard.</p> <p>First you need to clone the git repository from GitHub using the following command:</p> <pre><code>git clone https://github.com/martin-ueding/geo-activity-playground.git\n</code></pre> <p>That will create a directory <code>geo-activity-playground</code> in your current working directory.</p> <p>Then change into that directory:</p> <pre><code>cd geo-activity-playground\n</code></pre> <p>Next we will use Poetry to install the dependencies of the project. First you need to make sure that you have Poetry available. On Ubuntu/Debian run <code>sudo apt install python3-poetry</code>, on Fedora/RedHat run <code>sudo dnf install poetry</code> to install it.</p> <p>Then we can create the virtual environment:</p> <pre><code>poetry install\n</code></pre> <p>And next we can run the program:</p> <pre><code>poetry run geo-activity-playground --basedir path/to/your/playground --help\n</code></pre> <p>Replace the <code>--help</code> with the subcommands described in the help message or the other parts described this documentation.</p> <p>You will need the <code>--basedir</code> option because you run the program from the source directory and not from your playground directory. If you install the stable version via PIP as described in the other page, you will not need this option.</p>"},{"location":"getting-started/installing-git-on-linux/#updating-to-the-latest-version","title":"Updating to the latest version","text":"<p>Over time I will add more commits to the source control system. In order to update your clone to the latest version, execute the following:</p> <pre><code>git pull\n</code></pre> <p>This will download the missing changesets and apply them to your downloaded version. After that is done, you need to update your virtual environment with this:</p> <pre><code>poetry install\n</code></pre> <p>And then you can continue using it as before.</p>"},{"location":"getting-started/installing-stable-on-linux/","title":"Installing Stable On Linux","text":"<p>In this how-to guide I will show you how you can install the latest stable version of this project on Linux.</p>"},{"location":"getting-started/installing-stable-on-linux/#pipx-method","title":"PIPX method","text":"<p>The ideal way to install this project, is using <code>pipx</code>. First ensure that you have it installed:</p> Distribution Command Ubuntu, Debian <code>sudo apt install pipx</code> Fedora, RedHat <code>sudo dnf install pipx</code> Arch, Manjaro <code>sudo pacman -Syu python-pipx</code> <p>Using PIPX, you can then install the latest version using this command:</p> <pre><code>pipx install geo-activity-playground\n</code></pre> <p>That should be it. You might need to ensure that the <code>$PATH</code> is correct. For that see the section below.</p>"},{"location":"getting-started/installing-stable-on-linux/#pip-method","title":"PIP method","text":"<p>If you don't want to use PIPX, you can also use regular PIP. First install PIP:</p> Distribution Command Ubuntu, Debian <code>sudo apt install python3-pip</code> Fedora, RedHat <code>sudo dnf install python3-pip</code> Arch, Manjaro <code>sudo dnf install python-pip</code> <p>Then install the package into your user directory.</p> <pre><code>pip install --user geo-activity-playground\n</code></pre> <p>That should be it. You might need to ensure that the <code>$PATH</code> is correct. For that see the section below.</p>"},{"location":"getting-started/installing-stable-on-linux/#ensure-that-the-path-is-correct","title":"Ensure that the PATH is correct","text":"<p>Next you can try to start the program by just entering the following into the terminal:</p> <pre><code>geo-activity-playground --help\n</code></pre> <p>If you get a help message, everything is fine. If you get an error about command not found, we need to adjust your PATH. Execute the following in your command line:</p> <pre><code>xdg-open ~/.profile\n</code></pre> <p>This brings up an editor with your shell profile. Add a line containing the following at the end of the file:</p> <pre><code>PATH=$PATH:$HOME/.local/bin\n</code></pre> <p>This adds the path to your shell environment. This becomes active after you log in again. In order to apply it also to your current shell session, execute <code>export PATH=$PATH:$HOME/.local/bin</code> in the terminal window. Try the first command in this section again, you should see the help message now.</p>"},{"location":"getting-started/installing-stable-on-linux/#upgrading-to-the-latest-version","title":"Upgrading to the latest version","text":"<p>At some later point you likely want to upgrade to the latest version. For this use this command if you used PIPX:</p> <pre><code>pipx upgrade geo-activity-playground\n</code></pre> <p>If you used PIP, use this:</p> <pre><code>pip install --user --upgrade geo-activity-playground\n</code></pre>"},{"location":"getting-started/installing-stable-on-windows/","title":"Installing Stable on Windows","text":"<p>This how-to will show you the installation of the project on Windows. Here in the guide we use Windows 10 with the locale set to German, it should generalize to Windows 11 as well.</p>"},{"location":"getting-started/installing-stable-on-windows/#installing-python","title":"Installing Python","text":"<p>First we need to install Python because that doesn't ship with Windows. Fortunately we can get it from the Microsoft Store. Open that via the start menu and you should see something like this:</p> <p></p> <p>Type \u201cPython\u201d into the search bar at the top. In the search results you likely see different Python versions like 3.11 and 3.10. The project is compatible with 3.10 to 3.12; I'd suggest to just go with 3.12. In case that you have already installed one of the other compatible versions, you can skip this step.</p> <p>Here we select Python 3.11.</p> <p></p> <p>In the top right there is a blue button to install the software. Click that.</p>"},{"location":"getting-started/installing-stable-on-windows/#installing-the-project","title":"Installing the project","text":"<p>After that has run through, you need to open the Power Shell via the start menu. It should open a command line window like this:</p> <p></p> <p>We can verify that Python is working by entering <code>python --version</code> and <code>pip --version</code>. It should give a sensible version message like this:</p> <p></p> <p>Then we can ues PIP to install the project. Type the following:</p> <pre><code>pip install -U geo-activity-playground\n</code></pre> <p>It should look like this:</p> <p></p> <p>Then press Enter and it will install it, looking like this:</p> <p></p> <p>That might take a while. After that has run through, it should give a success message:</p> <p></p> <p>Then we're done with this window, you can close it now.</p>"},{"location":"getting-started/installing-stable-on-windows/#putting-your-activity-files-in-place","title":"Putting your activity files in place","text":"<p>Next you need to create a folder to put the files. I've placed mine just into the Documents folder. In there I've created a folder named exactly \u201cActivities\u201d.</p> <p></p> <p>Inside this folder there are my GPX/FIT/TCX/KML files as outlined in how-to guide on using activity files.</p> <p></p> <p>You need to have at least one activity file before you can start the program.</p>"},{"location":"getting-started/installing-stable-on-windows/#starting-the-webserver","title":"Starting the webserver","text":"<p>Once you have your activity files in place, we need to add a start script. Right-click into the playground folder (next to the \u201cActivities folder\u201d) and in the context menu select \u201cCreate New\u201d and then \u201cText File\u201d. Name it <code>start.bat</code>. Windows will ask you whether want to change the suffix (file extension) because it might get unusable. Yes, we want to do that. It should look like this:</p> <p></p> <p>Then right-click on that file and select \u201cEdit\u201d. A text editor will open up. Put the following content into this file:</p> <pre><code>python -m geo_activity_playground serve\npause\n</code></pre> <p>Then save and close it. I need you to create this file yourself and cannot offer a download because the Windows Defender will not allow you to execute such script files downloaded as a security precaution. If you create the file yourself, it will let you execute it.</p> <p>Once you have the <code>start.bat</code> there, you can double-click on it to execute it. A new terminal window should open and it should start to parse your activities.</p> <p></p> <p>After it has loaded everything, you can open http://127.0.0.1:5000/ in your browser. You should then see the landing page:</p> <p></p> <p>Also other functions like the heatmap work:</p> <p></p> <p>That's it, have fun!</p>"},{"location":"getting-started/moving-from-strava/","title":"Moving from Strava","text":"<p>If you have been using Strava up to this point but want to use this project from now on, this is the correct guide. Here I will show how you can convert your data from Strava into the format of this project and keep adding new data without Strava in the future.</p>"},{"location":"getting-started/moving-from-strava/#download-your-archive-from-strava","title":"Download your archive from Strava","text":"<p>Go to the Strava account download page and request a download of your data. This will take a while and you get a notification via e-mail when it is done.</p> <p>Once it has run through, you will be able to download a ZIP file. Once extracted, it will have a structure like this:</p> <pre><code>.\n\u251c\u2500\u2500 activities  [2217 entries exceeds filelimit, not opening dir]\n\u251c\u2500\u2500 activities.csv\n\u251c\u2500\u2500 applications.csv\n\u251c\u2500\u2500 bikes.csv\n\u251c\u2500\u2500 blocks.csv\n\u251c\u2500\u2500 categories_of_personal_information_we_collect.pdf\n\u251c\u2500\u2500 clubs\n\u251c\u2500\u2500 clubs.csv\n\u251c\u2500\u2500 comments.csv\n\u251c\u2500\u2500 community_content.json\n\u251c\u2500\u2500 community_personal_data.json\n\u251c\u2500\u2500 components.csv\n\u251c\u2500\u2500 connected_apps.csv\n\u251c\u2500\u2500 contacts.csv\n\u251c\u2500\u2500 email_preferences.csv\n\u251c\u2500\u2500 events.csv\n\u251c\u2500\u2500 favorites.csv\n\u251c\u2500\u2500 flags.csv\n\u251c\u2500\u2500 followers.csv\n\u251c\u2500\u2500 following.csv\n\u251c\u2500\u2500 general_preferences.csv\n\u251c\u2500\u2500 global_challenges.csv\n\u251c\u2500\u2500 goals.csv\n\u251c\u2500\u2500 group_challenges.csv\n\u251c\u2500\u2500 information_we_disclose_for_a_business_purpose.pdf\n\u251c\u2500\u2500 local_legend_segments.csv\n\u251c\u2500\u2500 logins.csv\n\u251c\u2500\u2500 media  [252 entries exceeds filelimit, not opening dir]\n\u251c\u2500\u2500 media.csv\n\u251c\u2500\u2500 memberships.csv\n\u251c\u2500\u2500 messaging.json\n\u251c\u2500\u2500 metering.csv\n\u251c\u2500\u2500 mobile_device_identifiers.csv\n\u251c\u2500\u2500 orders.csv\n\u251c\u2500\u2500 partner_opt_outs.csv\n\u251c\u2500\u2500 posts.csv\n\u251c\u2500\u2500 privacy_zones.csv\n\u251c\u2500\u2500 profile.csv\n\u251c\u2500\u2500 profile.jpg\n\u251c\u2500\u2500 reactions.csv\n\u251c\u2500\u2500 routes\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 1.gpx\n\u251c\u2500\u2500 routes.csv\n\u251c\u2500\u2500 segments.csv\n\u251c\u2500\u2500 shoes.csv\n\u251c\u2500\u2500 social_settings.csv\n\u251c\u2500\u2500 starred_routes.csv\n\u251c\u2500\u2500 starred_segments.csv\n\u251c\u2500\u2500 support_tickets.csv\n\u2514\u2500\u2500 visibility_settings.csv\n</code></pre> <p>This directory contains a file <code>activities.csv</code> with the metadata and also a directory <code>activities</code> with the files that you have recorded.</p>"},{"location":"getting-started/moving-from-strava/#convert-your-checkout","title":"Convert your checkout","text":"<p>Use the following command to create a directory from your Strava actitivies:</p> <pre><code>geo-activity-playground convert-strava-checkout ~/Downloads/export_123456/ ~/Documents/Outdoors/Playground\n</code></pre> <p>This should read through all the activities and create a directory structure with the pattern <code>~/Documents/Outdoors/Playground/Activities/{Kind}/{Equipment}/{Commute}/{Date} {Time} {Name}.{Suffix}</code>. For instance one file might be named <code>Activities/Run/5212701.0/2019-07-09 09-59-25 Around the \u5317\u4eac\u5927\u5b66 campus.gpx.gz</code>.</p> <p>The equipment might have nonsensical seeming names like <code>10370891.0</code>. The problem here is that Strava doesn't export the list of activities with that index. If your equipment doesn't have a nickname, it will just be such a number.</p>"},{"location":"getting-started/moving-from-strava/#use-the-directory","title":"Use the directory","text":"<p>Now that the files from Strava are converted, consult the guide on using activity files to proceed from here.</p>"},{"location":"getting-started/moving-from-strava/#recording-more-activities","title":"Recording more activities","text":"<p>Now that you don't record via Strava, you will need some other app to record your activities. There are Apps like OsmAnd or OpenTracks which provide such functionality. Export the files as GPX, FIT, TCX or KML files and put them into the directory structure. On the next start of the program, they will be picked up.</p>"},{"location":"getting-started/starting-the-webserver/","title":"Starting The Webserver","text":"<p>Before you start here, you should have done these things:</p> <ul> <li>You have installed the program either from a stable version or from git.</li> <li>You have set up a playground with either activity files or the Strava API.</li> </ul> <p>Now we can start the webserver which provides most of the features. This is done with the <code>serve</code> command. So depending on how you have installed it, the commands could look like these:</p> <ul> <li><code>geo-activity-playground serve</code> if you are in the playground directory and have installed a stable version.</li> <li><code>geo-activity-playground --basedir ~/Dokumente/Karten/Playground serve</code> if your playground directory is somewhere else and you have installed a stable version.</li> <li><code>poetry run geo-activity-playground --basedir ~/Dokumente/Karten/Playground serve</code> if you have it from the git checkout and want to use local files in your directory as a data source.</li> </ul> <p>The webserver will start up and give you a bit of output like this:</p> <pre><code>2023-11-19 17:59:23 geo_activity_playground.importers.strava_api INFO Loading metadata file \u2026\n2023-11-19 17:59:23 stravalib.protocol.ApiV3 INFO GET 'https://www.strava.com/api/v3/athlete/activities' with params {'before': None, 'after': 1700392964, 'page': 1, 'per_page': 200}\n2023-11-19 17:59:23 geo_activity_playground.importers.strava_api INFO Checking for missing time series data \u2026\n * Serving Flask app 'geo_activity_playground.webui.app'\n * Debug mode: off\n2023-11-19 17:59:23 werkzeug INFO WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.\n * Running on http://127.0.0.1:5000\n2023-11-19 17:59:23 werkzeug INFO Press CTRL+C to quit\n</code></pre> <p>The warning about the development server is fine. We are using this only to play around, not to power a web service for other users.</p> <p>Open http://127.0.0.1:5000 to open the website in your browser. There might be some more messages about downloading and parsing data. The first startup will take quite some time. When it is done you will see something like this:</p> <p></p> <p>Click around and explore the various features.</p>"},{"location":"getting-started/starting-the-webserver/#setting-host-and-port","title":"Setting host and port","text":"<p>In case you don't like the default value of <code>127.0.0.1:5000</code>, you can use the optional command line arguments <code>--host</code> and <code>--port</code> to specify your values.</p>"},{"location":"getting-started/using-activity-files/","title":"Using Activity Files","text":"<p>Outdoor activities are usually recorded as <code>.GPX</code> or <code>.FIT</code> files. Some apps like OsmAnd , OpenTracks or Organic Maps, GPS handhelds, smartwatches or cycling computers give you these files.</p>"},{"location":"getting-started/using-activity-files/#supported-file-formats","title":"Supported file formats","text":"<ul> <li>FIT</li> <li>GPX</li> <li>TCX</li> <li>KML</li> <li>KMZ</li> <li>Simra CSV export</li> </ul>"},{"location":"getting-started/using-activity-files/#add-activity-files","title":"Add Activity Files","text":"<p>Before starting the service you need to create a folder for your activities and put at least one activity file in there.</p> <p>Create a <code>Playground</code> folder on your storage somewhere and add a subfolder <code>Activities</code>. There you can add your activity files. For example:</p> <pre><code>~/\n\u251c\u2500 Documents[or other location]/\n\u2502  \u251c\u2500 Playground/\n\u2502  \u2502  \u251c\u2500 Activities/\n\u2502  \u2502  \u2502  \u251c\u2500 2024-03-03-17-42-10 Home to Bakery.gpx\n</code></pre> <p>The program will treat the files as read-only and does not modify them.</p> <p>Once the service is running you can use the Uploader to add your files. You can manually rename, move or delete your activity files, but the program needs to reload to respect these changes. You can restart the program or visit <code>Scan New Activities</code> in the admin menu of the WebUI.</p>"},{"location":"getting-started/using-activity-files/#metadata-extraction","title":"Metadata extraction","text":"<p>Most activity file formats contain basic data like <code>date</code>, <code>time</code> and <code>track points</code>. Each activity in geo-activity-playground also has the metadata fields <code>kind</code>, <code>equipment</code> and <code>name</code>. They can be extracted from files that contain them.</p> <p>If no metadata is found, <code>kind</code> and <code>equipment</code> default to <code>Unknown</code>. The <code>name</code> is then extracted from the file name (without the suffix). So for <code>Activities/2024-03-03-17-42-10 Home to Bakery.gpx</code> the <code>name</code> is <code>2024-03-03-17-42-10 Home to Bakery</code>.</p>"},{"location":"getting-started/using-activity-files/#next-steps","title":"Next steps","text":"<p>Once you have your files put into the directory, you're all set and can proceed with the next steps.</p> <p>You can extend the directory structure to categorize your activities, see Advanced Metadata Extraction.</p>"},{"location":"getting-started/using-strava-api/","title":"Using Strava API","text":"<p>You might have all your data on the Strava service and would like to use this for additional analytics without moving your data. That is fine.</p> <p>If you don't mind a bit of rate-limiting, you can just directly go ahead and start the webserver. It will offer to connect with Strava.</p>"},{"location":"getting-started/using-strava-api/#your-own-strava-app","title":"Your own Strava App","text":"<p>In order to use the Strava API without sharing the rate-limiting with other users, you need to create your own app. If my explanation doesn't suit you, have a look at this how-to guide as well.</p> <p>Navigate to the API settings page and create an app. It only needs to have read permissions.</p> <p>After you are done with that, you can see your App here:</p> <p></p> <p>There is a \"client ID\" and a \"client secret\" that we are going to need for the next step. In general our app could be used by all sorts of people who can then access their data only. We want to access our own data, but we still need to authorize our app to use our data. </p> <p>Open the webserver of this program and go the Strava API setup page. Enter your client ID and client secret, click on \"Connect to Strava\".</p> <p>This will prompt an OAuth2 request where you have to grant permissions to your app. After that you will be redirected back to the app and it should be set up. At the moment you need to restart the webserver such that it can start to download the activities. Due to rate-limiting it can still take a while.</p>"},{"location":"getting-started/using-strava-api/#use-export-to-avoid-rate-limiting","title":"Use export to avoid rate limiting","text":"<p>When you first start this program and use the Strava API as a data source, it will download the metadata for all your activities. Then it will start to download all the time series data for each activity. Strava has a rate limiting, so after the first 200 activities it will crash and you will have to wait for 15 minutes until you can try again and it will download the next batch.</p> <p>Therefore it is recommended to use a Strava export in order to get started quicker. For this go to the Strava account download page and download all your data. You will get a ZIP file. Unpack the files into <code>Playground/Strava Export</code>. These will be picked up there. Activities from Strava will only be downloaded after importing all these, and only the ones after the last one in the export will be downloaded. This way you can get started much quicker.</p>"},{"location":"getting-started/using-strava-api/#skip-strava-download","title":"Skip Strava download","text":"<p>If you don't want to download new activities from Strava, use <code>--skip-reload</code> to have the webserver start right away.</p>"},{"location":"reference/changelog/","title":"Changelog","text":"<p>This is the log of high-level changes that I have done in the various versions.</p>"},{"location":"reference/changelog/#version-0","title":"Version 0","text":"<p>This is the pre-release series. Things haven't settled yet, so each minor version might introduce breaking changes.</p>"},{"location":"reference/changelog/#version-035","title":"Version 0.35","text":""},{"location":"reference/changelog/#version-0351","title":"Version 0.35.1","text":"<ul> <li>GH-208: Support activity files with uppercase suffix.</li> <li>Do some internal changes to the map background generation for share pictures.</li> <li>Do some refactoring in the web code.</li> </ul>"},{"location":"reference/changelog/#version-0350","title":"Version 0.35.0","text":"<ul> <li>Add button to explorer tile map to remove map background.</li> </ul>"},{"location":"reference/changelog/#version-034","title":"Version 0.34","text":""},{"location":"reference/changelog/#version-0342","title":"Version 0.34.2","text":"<ul> <li>Host another JavaScript asset locally.</li> </ul>"},{"location":"reference/changelog/#version-0341","title":"Version 0.34.1","text":"<ul> <li>Host all assets locally to avoid using CDNs.</li> </ul>"},{"location":"reference/changelog/#version-0340","title":"Version 0.34.0","text":"<ul> <li>GH-197: Enforce UTF-8 encoding when reading the <code>activities.csv</code> from the Strava export.</li> <li>GH-197: Make CSV header parsing a bit more robust.</li> <li>GH-201: Correct label for equipment \"kinds\" plot.</li> <li>GH-203: Fix documentation, remove <code>--skip-strava</code> and replace it with <code>--skip-reload</code>.</li> <li>GH-205: Fix mismatch between ISO week and regular year.</li> <li>GH-157: Add a share picture per day.</li> </ul>"},{"location":"reference/changelog/#version-033","title":"Version 0.33","text":""},{"location":"reference/changelog/#version-0334","title":"Version 0.33.4","text":"<ul> <li>Add compatibility for Python 3.13.</li> </ul>"},{"location":"reference/changelog/#version-0333","title":"Version 0.33.3","text":"<ul> <li>GH-200: Fix startup without any activities.</li> <li>Fix upload when there is no <code>Activities</code> directory.</li> </ul>"},{"location":"reference/changelog/#version-0332","title":"Version 0.33.2","text":"<ul> <li>GH-198: Fix explorer map. The problem was that VS Code auto-formatted the embedded JavaScript and created syntax errors.</li> </ul>"},{"location":"reference/changelog/#version-0331","title":"Version 0.33.1","text":"<ul> <li>GH-156: Fix little bug with <code>_meta</code>.</li> </ul>"},{"location":"reference/changelog/#version-0330","title":"Version 0.33.0","text":"<ul> <li>Make heatmap colormap configurable via web UI.</li> <li>GH-196: Make tile map URL configurable via configuration file.</li> <li>Make daily pulse plot per year in tabs.</li> </ul>"},{"location":"reference/changelog/#version-0320","title":"Version 0.32.0","text":"<ul> <li>GH-173: Add config option <code>ignore_suffixes</code> which can be set to something like <code>[\".kml\"]</code> to ignore certain file types.</li> <li>Include all activities in the summary, even those which are not to be considered for achievements.</li> <li>Remove debug print.</li> <li>Make share picture always the same size independent of the content.</li> </ul>"},{"location":"reference/changelog/#version-0310","title":"Version 0.31.0","text":"<ul> <li>GH-189: Fix heatmap tile cache expiry in cases where the activity kind has changed.</li> <li>Make date and time formats better to read.</li> <li>GH-156: Add metadata editing functionality with override files.</li> </ul>"},{"location":"reference/changelog/#version-0300","title":"Version 0.30.0","text":"<ul> <li>GH-187: Update favicon to new logo.</li> <li>GH-174: Add new search functionality that also serves as an overview over all activities.</li> <li>GH-168: Clicking on table headers will sort the tables now.</li> <li>GH-162: Make track segmentation configurable with a configuration setting.</li> <li>Visualize cadence on the activity page.</li> <li>GH-188: Remove <code>root=</code> prefix in activity kind when importing from Strava.</li> <li>GH-188: Add option to rename activity kinds.</li> </ul>"},{"location":"reference/changelog/#version-029","title":"Version 0.29","text":""},{"location":"reference/changelog/#version-0292","title":"Version 0.29.2","text":"<ul> <li>Documentation improvements by beautiful-orca: GH-180, GH-181, GH-182, GH-183, GH-185</li> <li>GH-184: Use Python 3.12 in Docker.</li> <li>GH-178: Fix display of number of new tiles in activity view.</li> <li>GH-177: Fix distance from new <code>stravalib</code> version.</li> <li>GH-179: Work around Pandas deprecation message.</li> <li>GH-176: Do not modify filename on upload any more.</li> <li>GH-175: Mention Organic Maps.</li> </ul>"},{"location":"reference/changelog/#version-0291","title":"Version 0.29.1","text":"<ul> <li>GH-167: Fix explorer tile export.</li> <li>GH-169: Fix import of KML files with waypoints.</li> </ul>"},{"location":"reference/changelog/#version-0290","title":"Version 0.29.0","text":"<ul> <li>Use dropdown menus to make navigation a bit smaller.</li> <li>GH-163: Recompute explorer tiles when there are deleted activities. Previously this would lead to <code>KeyError</code> when trying to use the heatmap or the explorer tile maps.</li> <li>GH-161: Fix explorer tile clusters and square if one has activities that are not to be considered for achievements.</li> <li>GH-164: Create new function to handle write-and-replace on Windows.</li> <li>GH-155: Use the same scale for all plots with kind, make this configurable in the settings menu.</li> <li>Rewrite the documentation start page to make it more appealing and reflect the work in the web interface.</li> <li>GH-166: Add map with new explorer tiles to activity view.</li> <li>GH-160: Update version of <code>stravalib</code> and with that also <code>pydantic</code>. That fixes a bug with <code>recursive_guard</code>.</li> </ul>"},{"location":"reference/changelog/#version-028","title":"Version 0.28","text":"<ul> <li>Add settings menu to suppress fields from share pictures.</li> <li>Fix spelling mistake in navigation bar.</li> <li>Accelerate the tile visit computation.</li> <li>Ignore equipment offsets of equipments that don't exist.</li> <li>Reset corrupt heatmap cache files.</li> <li>GH-159: Improve password mechanism to protect both upload and settings.</li> <li>Document the use of Open Street Map uMap for missing explorer tiles on the go.</li> </ul>"},{"location":"reference/changelog/#version-027","title":"Version 0.27","text":""},{"location":"reference/changelog/#version-0271","title":"Version 0.27.1","text":"<ul> <li>Fix <code>num_processes</code> option.</li> </ul>"},{"location":"reference/changelog/#version-0270","title":"Version 0.27.0","text":"<ul> <li>GH-128: Let the Strava Checkout importer set the file <code>strava-last-activity-date.json</code> which is needed such that the Strava API importer can pick up after all the activities that have been imported via the checkout.</li> <li>GH-143: Use custom CSV parser to read activities that have newlines in their descriptions.</li> <li>GH-146: Make multiprocessing optional with <code>num_processes = 1</code> in the configuration.</li> <li>GH-147: Add another safeguard against activities that don't have latitude/longitude data.</li> <li>GH-149: Only pre-compute explorer maps for zoom 14 and 17 by default. Other ones just have to be enabled once. This saves a bit of computing time for most people that don't need to go down to zoom 19.</li> <li>GH-151: Do not fail if version cannot be determined.</li> <li>Add settings menu where one can configure various things:</li> <li>Equipment offsets</li> <li>Maximum heart rate for heart rate zones</li> <li>Metadata extractions from paths</li> <li>Privacy zones</li> <li>Strava connection</li> <li>The <code>config.json</code> replaces the <code>config.toml</code> and will automatically be generated.</li> <li>Fix bug in explorer tile interpolation that likely doesn't have an effect in practice.</li> </ul>"},{"location":"reference/changelog/#version-026","title":"Version 0.26","text":""},{"location":"reference/changelog/#version-0263","title":"Version 0.26.3","text":"<ul> <li>GH-142: Require <code>pandas &gt;= 2.2.0</code> to make sure that it knows about <code>include_groups</code>.</li> <li>GH-144: Ignore activities without time series when using the Strava Checkout import.</li> </ul>"},{"location":"reference/changelog/#version-0262","title":"Version 0.26.2","text":"<ul> <li>Start with a test suite for the web server that also tests importing.</li> <li>Already fixed a few little bugs with that.</li> <li>GH-141: Fix summary page if there are no activities with steps.</li> </ul>"},{"location":"reference/changelog/#version-0261","title":"Version 0.26.1","text":"<ul> <li>GH-139, GH-140: More fixes for Strava archive importer.</li> </ul>"},{"location":"reference/changelog/#version-0260","title":"Version 0.26.0","text":"<ul> <li>Add automatic dark mode.</li> <li>Add some more explanation for the Strava connection.</li> <li>GH-138: Fix import from Strava archive that was broken in 0.25.0.</li> <li>Style the settings page a bit.</li> </ul>"},{"location":"reference/changelog/#version-025","title":"Version 0.25","text":"<ul> <li>Restructure the way that activities are imported to realize a couple of benefits:</li> <li>Deleting activities is detected now, they are removed from the heatmap.</li> <li>If the code is changed, not everything has to be parsed again. This is especially helpful with regard to the rate-limited Strava API.</li> <li>Some code is deduplicated that had accumulated between activity file parsing and the Strava API.</li> <li>Unfortunately it means that everything needs to parsed again into the new format. I'm sorry about that, especially to you Strava users that need to deal with the rate limiting!</li> <li> <p>Add an web interface to connect to Strava API using a shared application such that it becomes much simpler to set up.</p> </li> <li> <p>GH-41: Compute moving time.</p> </li> <li>GH-127: Make calories and steps optional for the share picture.</li> <li>GH-131: Update to the column names in the Strava export.</li> <li>GH-133: Cope with manually recorded activities in Strava export.</li> <li>GH-134: Cope with broken FIT files.</li> </ul>"},{"location":"reference/changelog/#version-024","title":"Version 0.24","text":""},{"location":"reference/changelog/#version-0242","title":"Version 0.24.2","text":"<ul> <li>GH-127: Make calories and steps optional for the summary statistics.</li> </ul>"},{"location":"reference/changelog/#version-0241","title":"Version 0.24.1","text":"<ul> <li>GH-124: Add more timezone handling for Strava API.</li> <li>GH-125: Fix building of Docker container.</li> <li>GH-126: Fix heatmap download.</li> </ul>"},{"location":"reference/changelog/#version-0240","title":"Version 0.24.0","text":"<ul> <li>GH-43: Added nicer share pictures and privacy zones.</li> <li>GH-95: Display the number of new explorer tiles and squadratinhos per activity.</li> <li>GH-113: Open footer links in a new tab.</li> <li>GH-114: Show total distance and duration in day overview.</li> <li>GH-115: Add more summary statistics and add a \"hall of fame\" as well.</li> <li>GH-161: Show table for Eddington number, also update the plot to make it a bit easier to read. Add some more explanatory text.</li> <li>GH-118: Fix links in search results.</li> <li>GH-121: Fix link to share picture.</li> <li>GH-122: Convert everything to \"timezone naive\" dates in order to get rid of inconsistencies.</li> <li>GH-123: Fix startup from empty cache. A cache migration assumed that <code>activities.parquet</code> exists. I've added a check.</li> <li>Use Flask Blueprints to organize code.</li> <li>Remove half-finished \"locations\" feature from the navigation.</li> <li>Allow filtering the heatmap by activity kinds.</li> <li>Remove duplicate link to landing page from navigation.</li> </ul>"},{"location":"reference/changelog/#version-023","title":"Version 0.23","text":"<ul> <li>GH-111: Add password protection for upload.</li> <li>Use Flask \u201cflash\u201d messages.</li> <li>GH-110: Support routes that don't have time information attached them. That might be useful if you haven't recorded some particular track but still want it to count towards your heatmap and explorer tiles.</li> </ul>"},{"location":"reference/changelog/#version-022","title":"Version 0.22","text":"<ul> <li>GH-111: Allow uploading files from within the web UI and parse them directly after uploading.</li> <li>Fix bug that lead to re-parsing of activity files during startup.</li> </ul>"},{"location":"reference/changelog/#version-021","title":"Version 0.21","text":""},{"location":"reference/changelog/#version-0212","title":"Version 0.21.2","text":"<ul> <li>Fix crash in search due to missing <code>distance/km</code>.</li> </ul>"},{"location":"reference/changelog/#version-0211","title":"Version 0.21.1","text":"<ul> <li>Add support for Python 3.12.</li> </ul>"},{"location":"reference/changelog/#version-0210","title":"Version 0.21.0","text":"<ul> <li> <p>Breaking change: New way to extract metadata from paths and filenames. This uses regular expressions and is more versatile than the heuristic before. If you have used <code>prefer_metadata_from_file</code> before, see the documentation on activity files for the new way.</p> </li> <li> <p>GH-105: Ignore similar activities that have vanished.</p> </li> <li>GH-106: Be more strict when identifying jumps in activities. Take 30 s and 100 m distance as criterion now.</li> <li>GH-107: Remove warning by fixing a Pandas slice assignment.</li> <li>GH-108: Calories and steps are now extracted from FIT files.</li> <li> <p>GH-109: Better error message when trying to start up without any activity files.</p> </li> <li> <p>Removed <code>imagehash</code> from the dependencies.</p> </li> <li>Single day overview is now linked from each activity.</li> <li>Parsing of activity files is now parallelized over all CPU cores and faster than before.</li> <li>The coloring of the speed along the activity line doesn't remove outliers any more.</li> </ul>"},{"location":"reference/changelog/#version-020","title":"Version 0.20","text":"<ul> <li>GH-88: Fix failure to import Strava distance stream due to <code>unsupported operand type(s) for /: 'list' and 'int'</code>.</li> <li>GH-90: Take time jumps into account in activity distance computation and the various plots of the activities.</li> <li>GH-91: Import altitude information from GPX files if available.</li> <li>GH-92: Keep identity of activities based on hash of the file content, not the path. This allows to rename activities and just update their metadata, without having duplicates.</li> <li>GH-99: Skip Strava export activities that don't have a file.</li> <li>GH-98: Also accept boolean values in commute column of Strava's <code>activities.csv</code>.</li> <li>GH-100: Protect fingerprint computation from bogus values</li> <li>GH-102: Make dependency on <code>vegafusion[embed]</code> explicit in the dependencies.</li> <li>GH-103: Delete old pickle file before moving the new one onto it.</li> </ul>"},{"location":"reference/changelog/#version-019","title":"Version 0.19","text":""},{"location":"reference/changelog/#version-0191","title":"Version 0.19.1","text":"<ul> <li>Fix broken import of CSV files due to missing argument <code>opener</code>.</li> </ul>"},{"location":"reference/changelog/#version-0190","title":"Version 0.19.0","text":"<ul> <li>GH-88: Fix confusion about the internal data type for distance. Most of the time it was in meter, but the display was always in kilometer. In order to make it more clear now, the internal data now only contains the field <code>distance_km</code> and everything is represented as kilometer internally now.</li> <li>Add more tooltip information in the plot on the landing page.</li> <li>GH-87: Add <code>prefer_metadata_from_file</code> configuration option.</li> <li>GH-17: Download calories from Strava via the detailed API.</li> <li>Add option <code>--skip-strava</code> to the <code>serve</code> command in order to start the webserver without reaching out to Strava first. This might be useful if the rate limit has been exceeded.</li> <li>GH-89: Refactor some paths into a module such that there are not so many redundant definitions around.</li> <li>GH-86: Attempt to also read Strava exports that are localized to German, though untested.</li> <li>GH-36: Add a square planner.</li> </ul>"},{"location":"reference/changelog/#version-018","title":"Version 0.18","text":"<ul> <li>Fix internal server error 500 when there are not-a-number entries in the speed. GH-85</li> <li>Display activity source path in detail view.</li> <li>Ignore files which start with a period. This should also avoid Apple Quarantine files. GH-83</li> <li>Allow to have both Strava API and activity files.</li> <li>Use an existing Strava Export to load activities, retrieve only the remainder from the Strava API.</li> <li>In the calender, give the yearly total.</li> </ul>"},{"location":"reference/changelog/#version-017","title":"Version 0.17","text":""},{"location":"reference/changelog/#version-0175","title":"Version 0.17.5","text":"<ul> <li>Convert FIT sport type enum to strings. GH-84</li> </ul>"},{"location":"reference/changelog/#version-0174","title":"Version 0.17.4","text":"<ul> <li>Try to use charset-normalizer to figure out the strange encoding. GH-83</li> </ul>"},{"location":"reference/changelog/#version-0173","title":"Version 0.17.3","text":"<ul> <li>Fix error handler for GPX encoding issues. GH-83</li> </ul>"},{"location":"reference/changelog/#version-0172","title":"Version 0.17.2","text":"<ul> <li>Fix FIT import failure when the sub-sport is none. GH-84</li> </ul>"},{"location":"reference/changelog/#version-0171","title":"Version 0.17.1","text":"<ul> <li>Use locally downloaded tiles for all maps, this way we do not need to download them twice for activities and explorer/heatmap.</li> <li>Localize SimRa files to local time zone. GH-80</li> <li>Parse speed unit from FIT file. There are many devices which record in m/s and not in km/h, yielding too low speeds in the analysis. This is now fixed. GH-82</li> <li>Skip <code>.DS_Store</code> files in the activity directory. GH-81</li> <li>From FIT files we also extract the grade, temperature and GPS accuracy fields if they are present. There is no analysis for them yet, though. Also extract the workout name, sport and sub-sport fields from FIT files. GH-81</li> <li>Add more logging to diagnose Unicode issue on macOS. GH-83</li> </ul>"},{"location":"reference/changelog/#version-0170","title":"Version 0.17.0","text":"<ul> <li>Fix bug which broke the import of <code>.tcx.gz</code> files.</li> <li>Add <code>Dockerfile</code> such that one can easily use this with Docker. GH-78</li> <li>Add support for the CSV files of the SimRa Project. GH-79</li> </ul>"},{"location":"reference/changelog/#version-016","title":"Version 0.16","text":""},{"location":"reference/changelog/#version-0164","title":"Version 0.16.4","text":"<ul> <li>Fix syntax error.</li> </ul>"},{"location":"reference/changelog/#version-0163","title":"Version 0.16.3","text":"<ul> <li>Ignore Strava activities without a time series.</li> </ul>"},{"location":"reference/changelog/#version-0162","title":"Version 0.16.2","text":"<ul> <li>Make heatmap images that are downloaded look the same as the interactive one.</li> <li>Always emit the path when there is something wrong while parsing an activity file.</li> </ul>"},{"location":"reference/changelog/#version-0161","title":"Version 0.16.1","text":"<ul> <li>Fix handling of TCX files on Windows. On that platform one cannot open the same file twice, therefore my approach failed. Now I close the file properly such that this should work on Windows as well.</li> </ul>"},{"location":"reference/changelog/#version-0160","title":"Version 0.16.0","text":"<ul> <li>Add feature to render heatmap from visible area. GH-73</li> <li>Remove heatmap image generation from clusters, remove Scikit-Learn dependency.</li> <li>Add offsets for equipment. GH-71</li> <li>Fix number of tile visits in explorer view. GH-69</li> <li>Add action to convert Strava checkout to our format. GH-65</li> <li>Filter out some GPS jumps. GH-54</li> <li>Add simple search function. GH-70</li> </ul>"},{"location":"reference/changelog/#version-015","title":"Version 0.15","text":""},{"location":"reference/changelog/#version-0153","title":"Version 0.15.3","text":"<ul> <li>Create temporary file for TCX parsing in the same directory. There was a problem on Windows where the program didn't have access permissions to the temporary files directory.</li> </ul>"},{"location":"reference/changelog/#version-0152","title":"Version 0.15.2","text":"<ul> <li>Try to open GPX files in binary mode to avoid encoding issues. GH-74</li> </ul>"},{"location":"reference/changelog/#version-0151","title":"Version 0.15.1","text":"<ul> <li>Add <code>if __name__ == \"__main__\"</code> clause such that one can use <code>python -m geo_activity_playground</code> on Windows.</li> </ul>"},{"location":"reference/changelog/#version-0150","title":"Version 0.15.0","text":"<ul> <li>Export all missing tiles in the viewport, not just the neighbors.</li> <li>Automatically retry Strava API when the rate limit is exhausted. GH-67</li> <li>Give more helpful error messages when the are no activity files present.</li> </ul>"},{"location":"reference/changelog/#version-014","title":"Version 0.14","text":""},{"location":"reference/changelog/#version-0142","title":"Version 0.14.2","text":"<ul> <li>Fix broken Strava import (bug introduced in 0.14.0).</li> </ul>"},{"location":"reference/changelog/#version-0141","title":"Version 0.14.1","text":"<ul> <li>Fix hard-coded part in KML import (bug introduced in 0.14.0).</li> </ul>"},{"location":"reference/changelog/#version-0140","title":"Version 0.14.0","text":"<ul> <li>Do more calculations eagerly at startup such that the webserver is more responsive. GH-58</li> <li>Allow setting host and port via the command line. GH-61</li> <li>Re-add download of explored tiles in area. GH-63</li> <li>Unify time handling, use UTC for all internal representations. GH-52</li> <li>Add some sort of KML support that at least works for KML exported by Viking. GH-62</li> </ul>"},{"location":"reference/changelog/#version-013","title":"Version 0.13","text":"<ul> <li>Revamp heatmap, use interpolated lines to provide a good experience even at high zoom levels.</li> <li>This also fixes the gaps that were present before. GH-34</li> <li>Add cache migration functionality.</li> <li>Make sure that cache directory is created beforehand. GH-55</li> <li>Split tracks into segments based on gaps of 30 seconds in the time data. That helps with interpolation across long distances when one has paused the recording. GH-47</li> <li>Fix introduced bug. GH-56</li> <li>Add cache to heatmap such that it doesn't need to render all activities and only add new activities as needed.</li> <li>Add a footer. GH-49</li> <li>Only export missing tiles in the active viewport. GH-53</li> <li>Add missing dependency to SciKit Learn again; I was too eager to remove that. GH-59</li> </ul>"},{"location":"reference/changelog/#version-012","title":"Version 0.12","text":"<ul> <li>Change coloring of clusters, have a color per cluster. Also mark the square just as an overlay.</li> <li>Fix bug with explorer tile page when the maximum cluster or square is just 1. GH-51</li> <li>Speed up the computation of the latest tiles.</li> </ul>"},{"location":"reference/changelog/#version-011","title":"Version 0.11","text":"<ul> <li>Add last activity in tile to the tooltip. GH-35</li> <li>Add explorer coloring mode by last activity. GH-45</li> <li>Actually implement <code>Activity/{Kind}/{Equipment}/{Name}.{Format}</code> directory structure.</li> <li>Document configuration file.</li> <li>Interpolate tracks to find more explorer tiles. GH-27</li> <li>Fix bug that occurs when activities have no distance information.</li> <li>Show time evolution of the number of explorer tiles, the largest cluster and the square size. GH-33</li> <li>Center map view on biggest explorer cluster.</li> <li>Show speed distribution. GH-42</li> </ul>"},{"location":"reference/changelog/#version-010","title":"Version 0.10","text":"<ul> <li>Use a grayscale map for the explorer tile maps. GH-38</li> <li>Explicitly write \u201c0 km\u201d in calendar cells where there are no activities. GH-39, GH-40</li> </ul>"},{"location":"reference/changelog/#version-09","title":"Version 0.9","text":"<ul> <li>Certain exceptions are not skipped when parsing files. This way one can gather all errors at the end. GH-29</li> <li>Support TCX files. GH-8</li> <li>Fix equipment view when using the directory source. GH-25</li> <li>Fix links from the explorer tiles to the first activity that explored them. GH-30</li> <li>Fix how the API response from Strava is handled during the initial token exchange. GH-37</li> </ul>"},{"location":"reference/changelog/#version-08","title":"Version 0.8","text":""},{"location":"reference/changelog/#version-083","title":"Version 0.8.3","text":"<ul> <li>Only compute the explorer tile cluster size if there are cluster tiles. Otherwise the DBSCAN algorithm doesn't work anyway. GH-24</li> <li>Remove allocation of huge array. GH-23</li> </ul>"},{"location":"reference/changelog/#version-082","title":"Version 0.8.2","text":"<ul> <li>Some FIT files apparently have entries with explicit latitude/longitude values, but those are null. I've added a check which skips those points.</li> </ul>"},{"location":"reference/changelog/#version-081","title":"Version 0.8.1","text":"<ul> <li>Fix reading of FIT files from Wahoo hardware by reading them in binary mode. GH-20.</li> <li>Fix divide-by-zero error in speed calculation. GH-21</li> </ul>"},{"location":"reference/changelog/#version-080","title":"Version 0.8.0","text":"<ul> <li>Make heart rate zone computation a bit more flexibly by offering a lower bound for the resting heart rate.</li> <li>Open explorer map centered around median tile.</li> <li>Compute explorer cluster and square size, print that. GH-2</li> <li>Make it compatible with Python versions from 3.9 to 3.11 such that more people can use it. GH-22</li> </ul>"},{"location":"reference/changelog/#version-07","title":"Version 0.7","text":"<ul> <li>Add Squadratinhos, which are explorer tiles at zoom 17 instead of zoom 14.</li> <li>Reduce memory footprint for explorer tile computation.</li> </ul>"},{"location":"reference/changelog/#version-06","title":"Version 0.6","text":"<ul> <li>Interactive map for each activity.</li> <li>Color explorer tiles in red, green and blue. GH-2</li> <li>Directly serve GeoJSON and Vega JSON embedded in the document.</li> <li>Automatically detect which source is to be used. GH-16</li> <li>Fix the name of the script to be <code>geo-activity-playground</code> and not just <code>geo-playground</code>. GH-11</li> <li>Add mini maps to the landing page. GH-9</li> <li>Add fullscreen button to the maps. GH-4</li> <li>Add favicon. GH-19</li> <li>Added some more clever caching to the explorer tiles such that loading the page with explorer tiles comes up in just a few seconds.</li> <li>Add a triplet of time series plots (distance, altitude, heart rate) for each activity.</li> <li>Show plot for heart rate zones per activity. GH-12</li> <li>Handle activities without any location points. GH-10</li> <li>Resolve Strava Gear name. GH-18</li> <li>Add page for equipment. GH-3</li> <li>Add a pop-up with some metadata about the first visit to the explorer tiles. GH-14</li> <li>Integrate missing explorer tiles into the web interface. GH-7.</li> <li>Color activity line with speed. GH-13</li> <li>Add interactive heatmap.</li> <li>Add margin to generated heatmaps. GH-1</li> </ul>"},{"location":"reference/changelog/#version-05","title":"Version 0.5","text":"<ul> <li>Add some plots for the Eddington number. GH-3</li> </ul>"},{"location":"reference/changelog/#version-04","title":"Version 0.4","text":"<ul> <li>Add some more plots.</li> </ul>"},{"location":"reference/changelog/#version-03","title":"Version 0.3","text":"<ul> <li>Start to build web interface with Flask.</li> <li>Remove tqdm progress bars and use colorful logging instead.</li> <li>Add interactive explorer tile map.</li> </ul>"},{"location":"reference/changelog/#version-02","title":"Version 0.2","text":"<ul> <li>Unity command line entrypoint.</li> <li>Crop heatmaps to fit.</li> <li>Export missing tiles as GeoJSON.</li> <li>Add Strava API.</li> <li>Add directory source.</li> </ul>"},{"location":"reference/changelog/#version-01","title":"Version 0.1","text":""},{"location":"reference/changelog/#version-013_1","title":"Version 0.1.3","text":"<ul> <li>Generate some heatmap images.</li> <li>Generate an explorer tile video.</li> </ul>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Geo Activity Playground","text":"<p>This is a software to view recorded outdoor activities and derive various insights from your data collection. All data is kept on your machine, hence it is suitable for people who have an affinity for data analysis and privacy.</p> <p>It caters to serve a similar purpose as Strava with Statshunters statshunters does but while not requiring you to share your location data with a service provider.</p> <p>One can use this program with a local collection of activity files (GPX, FIT, TCX, KML, CSV) or via the Strava API. The latter is appealing to people who want to keep their data with Strava primarily. In case that one wants to move, this might provide a noncommital way of testing out this project.</p> <p>The main user interface is web-based, you can run this on your Linux, Mac or Windows laptop. If you want, it can also run on a home server or your personal cloud instance.</p>"},{"location":"#screenshot-tour","title":"Screenshot tour","text":"<p>This is the view of a single activity:</p> <p></p> <p>You also get a beautiful interactive heatmap of all your activities:</p> <p></p> <p>Also there are plenty of summary statistics that lets you track how many rides, walks or hikes you have done:</p> <p></p> <p>If you're into explorer tiles or squadratinhos, this got you covered:</p> <p></p> <p>The configuration options are available within the interface such that you do not have to work with configuration files (like in earlier versions):</p> <p></p>"},{"location":"#get-started","title":"Get started","text":"<p>Install the software using one of the following options:</p> <ul> <li>Using the stable version on Linux</li> <li>Using the stable version on Windows</li> <li>Using the development version on Linux</li> </ul> <p>Get your activity data in place using one of the following options:</p> <ul> <li>Use local activity files if you already have these.</li> <li>Use the Strava API if you want to use this project to analyse your data on Strava.</li> <li>Move from Strava if you wan to leave Strava and work locally from then on.</li> </ul>"},{"location":"#free-software","title":"Free software","text":"<p>You can find the code on GitHub where you can also file issues. If you would like to use this yourself or contribute, feel free to reach out via the contact options from my website. I would especially appreciate improvements to the documentation. If you're familiar with Markdown and GitHub, you can also directly create a pull request. The code is licensed under the very permissive MIT license.</p>"},{"location":"acknowledgments/","title":"Acknowledgments","text":"<p>This project builds on many amazing other projects and would not be possible without them.</p>"},{"location":"acknowledgments/#bootstrap-css","title":"Bootstrap CSS","text":"<p>Writing CSS is not a trivial task. For many projects I have been using the Bootstrap CSS Framework which provides sensible default values, a 12-column grid system and a lot of components. Using this I didn't have to write any CSS myself and just attach a couple of classes to HTML elements.</p>"},{"location":"acknowledgments/#coloredlogs","title":"coloredlogs","text":"<p>Log messages in multiple colors are neat. Using the coloredlogs package we can get these super easily.</p>"},{"location":"acknowledgments/#fitdecode","title":"fitdecode","text":"<p>For reading FIT files I use the fitdecode library which completely handles all the parsing of this file format.</p>"},{"location":"acknowledgments/#flask","title":"Flask","text":"<p>The webserver is implemented with Flask which provides a really easy way to get started. It also ships with a development webserver which is enough for this project at the moment.</p>"},{"location":"acknowledgments/#geojson","title":"GeoJSON","text":"<p>Transferring geographic geometry data from the Python code to Leaflet is easiest with using the GeoJSON format. The official standard RFC is a bit hard to read, rather have a look at the Wikipedia article. And there is an online viewer that you can try out.</p>"},{"location":"acknowledgments/#github","title":"GitHub","text":"<p>For a smooth open source project one needs a place to share the code and collect issues. GitHub provides all of this for free.</p>"},{"location":"acknowledgments/#gpxpy","title":"gpxpy","text":"<p>For reading GPX files I use the gpxpy library. This allows me to read those files without having to fiddle with the underlying XML format.</p>"},{"location":"acknowledgments/#leaflet","title":"Leaflet","text":"<p>The interactive maps on the website are powered by Leaflet, a very easy to use JavaScript library for embedding interactive Open Street Map maps. It can also display GeoJSON geometries natively, of which I also make heavy use.</p>"},{"location":"acknowledgments/#mkdocs","title":"MkDocs","text":"<p>Writing documentation is more fun with a nice tool, therefore I use MkDocs together with Material for MkDocs. This powers this documentation.</p>"},{"location":"acknowledgments/#open-street-map","title":"Open Street Map","text":"<p>All the maps displayed use tiles from the amazing Open Street Map. This map is created by volunteers, the server hosting is for free. Without these maps this project would be quite boring.</p>"},{"location":"acknowledgments/#pandas","title":"Pandas","text":"<p>Working with thousands of activities, thousands of tiles and millions of points makes it necessary to have a good library for number crunching structured data. Pandas offers this and gives good performance and many features.</p>"},{"location":"acknowledgments/#parquet","title":"Parquet","text":"<p>I need to store the intermediate data frames that I generate with Pandas. Storing as JSON has disadvantages because dates are not properly encoded. Also it is a text format and quite verbose. The Parquet format is super fast and memory efficient.</p>"},{"location":"acknowledgments/#poetry","title":"Poetry","text":"<p>For managing all the Python package dependencies I use Poetry which makes it very easy to have all the Python project housekeeping with one tool.</p>"},{"location":"acknowledgments/#python","title":"Python","text":"<p>Almost all of the code here is written in Python, a very nice and versatile programming language with a vast ecosystem of packages.</p>"},{"location":"acknowledgments/#requests","title":"Requests","text":"<p>For doing HTTP requests I use the Requests library. It provides a really easy to use interface for GET and POST requests.</p>"},{"location":"acknowledgments/#scikit-learn","title":"Scikit-learn","text":"<p>Finding out which cluster is the largest one can either be formed as a graph search problem or as a data science problem. Using the Scikit-learn library I can easily use the DBSCAN algorithm to find the clusters of explorer tiles.</p>"},{"location":"acknowledgments/#statshunters","title":"Statshunters","text":"<p>The Statshunters page allows to import the activities from Strava and do analysis like explorer tiles, Eddington number and many other things. This has served as inspiration for this project.</p>"},{"location":"acknowledgments/#strava","title":"Strava","text":"<p>Although I have recorded some of my bike rides, I only really started to record all of them when I started to use Strava. This is a nice platform to track all activities. They also offer a social network feature, which I don't really use. They provide some analyses of the data, but they lack some analyses which I have now implemented in this project.</p>"},{"location":"acknowledgments/#stravalib","title":"stravalib","text":"<p>Strava has an API, and with stravalib there exists a nice Python wrapper. This makes it much easier to interface with Strava.</p>"},{"location":"acknowledgments/#strava-local-heatmap","title":"Strava local heatmap","text":"<p>https://github.com/remisalmon/Strava-local-heatmap</p>"},{"location":"acknowledgments/#tcxreader","title":"tcxreader","text":"<p>https://github.com/alenrajsp/tcxreader</p>"},{"location":"acknowledgments/#vega-altair","title":"Vega &amp; Altair","text":"<p>https://altair-viz.github.io/index.html https://vega.github.io/vega/</p>"},{"location":"acknowledgments/#velo-viewer","title":"Velo Viewer","text":""},{"location":"features/activity-view/","title":"Activity View","text":"<p>When you have selected a particular activity, you can view various details about it. This is what the screen looks like, we will go through the different parts in the following.</p> <p></p>"},{"location":"features/activity-view/#metadata","title":"Metadata","text":"<p>You have a column with metadata about the activity. The activity kind, whether it is a commute and the equipment are currently only supported via the Strava API, but we can build something to infer that from directories as well.</p> <p></p> <p>The calories are broken in the Strava API wrapper library that I use, therefore they don't show even if they are there.</p> <p>You can also see the ID which is an internal ID. When you use Strava API as a source, it will use the IDs that Strava gives. When you use files from a directory it will be computed from a hash of the path to the activity file.</p>"},{"location":"features/activity-view/#map-with-track","title":"Map with track","text":"<p>The interactive map shows a line with the activity. The speed is color-coded and peaks at 35 km/h with a yellow color.</p> <p></p>"},{"location":"features/activity-view/#distance-speed-and-altitude","title":"Distance, speed and altitude","text":"<p>Then there are a couple of time series plots. One is the distance vs. time. You can see how much distance you covered when and also see plateaus when you went on a break.</p> <p></p> <p>From this we can also compute the speed, although that might be pretty noisy:</p> <p></p> <p>And more interesting is the distribution of the various speed zones. This gives you an understanding how much time you spent at which speed. The buckets are set in 5 km/h intervals, but we could also change that.</p> <p></p> <p>If the time series data has the altitude, which isn't always the case, you can see it in the plot there. Here we can see how I did a tour and continually rode downhill. Except at the end where I had to climb in order to get the explorer tile that I wanted.</p> <p></p>"},{"location":"features/activity-view/#heart-rate","title":"Heart rate","text":"<p>The heart rate isn't too helpful, I feel. Still I've created the plot from the given data.</p> <p></p> <p>More interesting regarding the heart rate are the zones which one has spent time during this activity.</p> <p></p> <p>The definition of the heart rate zones is not standardized. Usually there are five zones and they have the same names. What differs is how their ranges are computed and there is some chaos around that.</p> <p>All definitions that I found take the maximum heart rate as the upper limit. One can measure this as part of a professional training or just use the 220 minus age prescription which at least for me matches close enough. What they differ on is how they use a lower bound. It seems that Polar or REI basically use 0 as the lower bound. My Garmin system also uses 0 as the lower bound. But as one can see in this blog, one can also use the resting heart rate as the lower bound.</p> <p>Based on the maximum and resting heart rate we will then compute the heart rate zones using certain percentages of effort. We can compute the heart rate as the following:</p> <p>rate = effort \u00d7 (maximum \u2013 minimum) + minimum</p> <p>The zones then take the following efforts:</p> Zone Effort Training 1 50 to 60 % Warmup/Recovery 2 60 to 70 % Base Fitness 3 70 to 80 % Aerobic Endurance 4 80 to 90 % Anerobic Capacity 5 90 to 100 % Speed Training <p>You can decide how you want to do work with that. If you want to have the same definitions that say Garmin uses, you need to just enter your birth year and we can compute the rest. If you want to use a lower bound, you need to specify that.</p>"},{"location":"features/calendar/","title":"Calendar","text":"<p>In order to access all the activities, there is a calendar view. It shows the years in rows and the months in columns. Each cell is a particular month and indicates the total distance traveled.</p> <p></p> <p>When you click on any of the months, you will see a calendar for a given month. Here is one of my months which doesn't show too personal data:</p> <p></p> <p>Clicking on an activity will lead you to the activity detail view.</p>"},{"location":"features/eddington/","title":"Eddington Number","text":"<p>The astronomer Sir Arthur Eddington like to go on longer bike rides. Apparently he did a lot of rides and had 84 days where he rode at least 84 miles. The Eddington number for cycling was coined from this.</p> <p>If you have an Eddington number E, it means that you have had E days with at least E kilometer distance. At the time of writing my number is 62, which means that I rode at least 62 km on 62 separate days. If I want to extend it to 63, I would need to have at least 63 km on 63 separate days. My bike rides that are just 62 km long will not count any more, making this challenge really hard.</p> <p>In the following plot you can see in blue the number of days that exceed the given distance. You can see that I have a 998 days that exceed 1 km, that's pretty easy when one just records enough data over many years. But then there are only 259 days where I exceed 20 km as this is beyond the distance that I have when I only go for a walk or run some simple errands.</p> <p></p> <p>The red curve indicates how many rides one needs to get the Eddington number. As it is a semi-log plot, the straight line is curved like a log-curve.</p> <p>You can see this cliff at around 80 km. That is the distance that I ride to work and back. I have many days with around 80 km, but longer rides are only on occasional bike trips. Therefore I think I will eventually make it to an Eddington number of 80, but beyond that will be super difficult.</p> <p>This is a life-long challenge, so who knows what happens in the future.</p>"},{"location":"features/eddington/#length-unit","title":"Length unit","text":"<p>The definition of the Eddington number depends on the length unit that one has. Eddington as a British person used the English mile as a base unit. Therefore his number of 84 is actually harder to achieve than a 84 based on kilometers because he needed to exceed 135 km (84 mi) on each ride.</p> <p>Therefore using a different length unit as a base changes the meaning. The kilometer is easier, the mile (1609.344 m) is harder. One could also use nautical miles (1852 m). And while we are at arbitrary unit systems, we could also use furlongs (201.168 m).</p>"},{"location":"features/equipment/","title":"Equipment Overview","text":"<p>When activities are tagged with the used equipment, one can tally the total distance traveled with each thing. This given as a table with the recently used equipment at the top:</p> <p></p> <p>And for each thing there is also a graph which shows how the distance accumulates over time:</p> <p></p> <p>Here one can see how with my old bike I only recorded the occasional bike trip and not nearly the 4000 km/a which I was doing. And then it got stolen in 2019, so I bought a new bike.</p> <p>This metadata is downloaded via the Strava API, for the directory source it is not yet supported. I thought about using directories like <code>Activities/{Activity Kind}/{Equipment Name}/{Activity Name}.gpx</code>. to indicate the kind and equipment. If you're interested in implementing this, let me know.</p>"},{"location":"features/explorer-tiles/","title":"Explorer Tiles","text":"<p>Maps accessible via the web browser are usually served as little image tiles. The Open Street Map uses the Web Mercator coordinate system to map from latitude and longitude to pixels on the map.</p> <p>Each tile is 256\u00d7256 pixels in size. The zoom levels zoom in by a factor of two. Therefore all the tiles are organized in a quad tree. As you zoom in, each tile gets split into four tiles which can then show more detail. The following prescription maps from latitude and longitude (given in degrees) to tile indices:</p> <pre><code>def compute_tile(lat: float, lon: float, zoom: int = 14) -&gt; tuple[int, int]:\n    x = np.radians(lon)\n    y = np.arcsinh(np.tan(np.radians(lat)))\n    x = (1 + x / np.pi) / 2\n    y = (1 - y / np.pi) / 2\n    n = 2**zoom\n    return int(x * n), int(y * n)\n</code></pre> <p>At zoom level 14 the tiles have a side length of roughly 1.5 km in Germany. These tiles are used as the basis for explorer tiles. The basic idea is that every tile where you have at least one point in an activity is considered an explored tile.</p> <p>From your activities the program will extract all the tiles that you have visited. And then it does a few things with those. One main thing is that it will display these on an interactive map. When we zoom into one area where I've been on vacation in 2023, you can see the explored tiles there:</p> <p></p> <p>The filled tiles are explored, I have been there. The colored tiles are cluster tiles, that means that all their four neighbor tiles are also explored.</p> <p>You can see here how I have explored a region and ensured that it is mostly contiguous.</p> <p>There is another vacation from 2013 where I wasn't aware of the cluster tiles. I just did some bike trips and didn't look out for the tiles. There the tiles look like this:</p> <p></p> <p>You see all these gaps in there. Also there are three different clusters which are not connected. Each unique cluster is assigned a different color such that one can see where there are gaps between the cluster tiles. And filling the gaps is what the explorer tiles are about: This OCD (obsessive compulsive disorder) like craving to fill in the gaps.</p> <p>Let's take a look at my main cluster of explorer tiles. Here I have explored much more than in the areas where I was on vacation.</p> <p></p> <p>You can see an additional feature, the blue square. This is the one largest square which can be fit into all explored tiles. In this picture it has size 21\u00b2. The idea of the square is to have a really tough challenge. Not only does one need to explore increasingly many tiles to expand the square by one unit, there must not be any gaps.</p> <p>As you can see in this picture, there is a tile missing right at the top edge. I will never be able to get that because that is an off-limits area of the German air force at the airport. So I can expand my square to the south only.</p> <p>You can click on each tile and get some information about that particular tile. You can see when you first explored that and with which activity. Also it shows the last activity there as well as the number of activities. If it is a local cluster, it will also show the cluster size.</p> <p></p> <p>There is also the option to color the tiles by first or last visit. Use one of the buttons above the map:</p> <p></p> <p>Then the map will show the first visit:</p> <p></p> <p>Or how recent your last visit is:</p> <p></p> <p>This uses Matplotlib's Plasma scale (see below) to color the age of a tile. Very new tiles will get a yellow color, a year old tiles a reddish color and tiles two years old or older a colder blue. This is the scale:</p> <p></p> <p>You can switch this with the buttons above the map.</p>"},{"location":"features/explorer-tiles/#squadratinhos","title":"Squadratinhos","text":"<p>The explorer tiles at zoom level 14 are best suited for cycling and to discover the area around the city. There is a derived definition, the squadratinhos which are defined at zoom level 17 and therefore a factor 8 smaller in each direction. Each explorer tile is therefore divided into 256 squadratinhos.</p> <p>These are better suited for walking and making sure that you really explored every little place in your neighborhood. Since they are so small, there are many properties which one cannot go onto, like industrial sites, airports or just a wide river.</p> <p>For my home city it looks like this:</p> <p></p> <p>You can see how the squadratinhos are much smaller than the explorer tiles and how they lend themselves to more local exploring.</p>"},{"location":"features/explorer-tiles/#history","title":"History","text":"<p>The map only shows the current state of your explorer tiles. In order to get a sense of how many new tiles you have discovered in the past, there are also plots that show you how you have extended the total number of squares, the size of your largest cluster and the size of your largest square over time:</p> <p></p>"},{"location":"features/explorer-tiles/#missing-tile-files","title":"Missing tile files","text":"<p>Looking at these maps you can see the gaps. And if you feel challenged to fill those, you might want to plan a \u201ctactical bike ride\u201d to explore those. Let us take another look at my tile history in Sint Annaland:</p> <p></p> <p>You can see those gaps in the clusters. To make it easier to explore tiles while on the go, we can export a file with the missing tiles. Pan and zoom the map to an area which you want to export. Below the map you will find two links:</p> <p>Download missing tiles in visible area as GeoJSON or GPX.</p> <p>This export is available as GeoJSON or GPX such that you can open it with other applications. For instance with GPX See on Linux it looks like this when opening the GeoJSON file:</p> <p></p> <p>You can then upload the GeoJSON file to Bikerouter and it will display there:</p> <p></p> <p>Then plan a route that goes through as many tiles as possible. Download the route as GPX and use an app like OsmAnd to ride along it.</p>"},{"location":"features/explorer-tiles/#missing-tiles-on-the-go","title":"Missing tiles on the go","text":"<p>The above is nice to plan the route, perhaps you also want to take the missing tiles along to do spontaneous tile hunting.</p> <p>A possibility should be Organic Maps which is a FOSS app that can display offline maps and also show GPX files.</p> <p>Another method is to use Open Street Map uMap, either the one hosted in Germany or France. Then you can create a new personal map (consider limiting the access rights, default is public) and upload the GeoJSON file. Then you can use that map on the code to see your position and the missing tiles:</p> <p></p> <p>Yet another option is Offline Maps. That is able to display GeoJSON on Android, though one needs to buy the add-on for like 5 EUR.</p> <p>On Android one can use the OsmAnd app to display tracks and also try to visualize the missing tiles. Unfortunately GeoJSON is not supported, therefore one has to play some tricks. The missing tiles are also exported as a GPX file with a track for each missing tile. This looks strange, but it is a bit helpful with OsmAnd. This is how the file looks like in GPXSee:</p> <p></p> <p>And on OsmAnd such files look like this:</p> <p></p> <p>Unfortunately OsmAnd becomes a very sluggish with such a huge track imported, so make sure to only export it from rather small regions.</p>"},{"location":"features/explorer-tiles/#square-planner","title":"Square planner","text":"<p>From the explorer tile views you can open the square planner which allows you to see which tiles you need to explore in order to extend the square into a particular direction. The screen will open with the largest square that you have, then you can use the buttons to extend or move your square.</p> <p></p> <p>Using the buttons in the middle you can move the square, the buttons in the corners allow to extend or shrink the square.</p> <p>When you have selected the square that you want to target, you can download the missing files in for that square as GeoJSON or GPX.</p>"},{"location":"features/heatmaps/","title":"Heatmaps","text":"<p>A heatmap shows where you have been more often than other places. There is an interactive and zoomable heatmap that looks like this:</p> <p></p> <p>Here you can see where I mostly travel between Bonn and Cologne.</p> <p>You have the option to download a rendered heatmap from the current viewport of the interactive map as in image with up to 4000\u00d74000 pixels, there is a link below the map.</p>"},{"location":"features/kind-rename/","title":"Kind rename","text":"<p>Metadata and importing from several sources can be messy and in some cases Strava will export its acivity types/activity kinds under names like root='Ride' and not \"Ride\". That can lead to issues with tagging and the heatmap - in this case we have multiple, overlapping activity kinds for the same activity kinds.</p> <p>To fix this, go to Admin -&gt; Settings -&gt; Kind rename</p> <ul> <li>Type in the box to define how you want to reprocess your activities</li> <li>The Format is <code>Existing name =&gt; New name</code></li> <li>f.e. to rename <code>root='Ride'</code> to <code>'Ride'</code> put in <code>root='Ride' =&gt; Ride</code></li> <li>Click on \"Save\", the system will then reprocess all affected activities</li> <li>This can take a few minutes depending on the amount of activities</li> </ul>"},{"location":"features/overview/","title":"Overview page","text":"<p>When you start the webserver, you will see the overview page. It looks like the following and shows the activities you've done in the past 30 days:</p> <p></p> <p>Then below that you see the latest 15 activities with their tracks on interactive maps.</p> <p></p> <p>Each card contains the name, activity type, distance and duration. The non-commute activities are highlighted with a blue border, the commutes just have a gray border.</p> <p>Click on any of the names and you will see the details of that activity.</p>"},{"location":"features/share-picture/","title":"Share Picture","text":"<p>On each activity page you will find a \"share picture\" like the following:</p> <p></p>"},{"location":"features/share-picture/#privacy-zones","title":"Privacy zones","text":"<p>You might want to remove points that are close to your home, work or relatives. For this you can define arbitrary polygons as \"privacy zones\".</p> <p>To create such a polygon, go to GeoJSON.io. You will see a map similar to this one:</p> <p></p> <p>Select the polygon tool and click on the map to span the polygon.</p> <p></p> <p>Once you are done, press Enter to finish the polygon. In the left panel the GeoJSON output will appear:</p> <p></p> <p>For this case, we have this GeoJSON:</p> <pre><code>{\n  \"type\": \"FeatureCollection\",\n  \"features\": [\n    {\n      \"type\": \"Feature\",\n      \"properties\": {},\n      \"geometry\": {\n        \"coordinates\": [\n          [\n            [\n              6.87987514009842,\n              50.68272071401333\n            ],\n            [\n              6.878628929151887,\n              50.6819310903943\n            ],\n            [\n              6.8780142440226655,\n              50.68125883278765\n            ],\n            [\n              6.879563587362242,\n              50.68022375065988\n            ],\n            [\n              6.880599289703014,\n              50.68029311254671\n            ],\n            [\n              6.8814665851591315,\n              50.68102940933676\n            ],\n            [\n              6.881542368256589,\n              50.681723011688035\n            ],\n            [\n              6.8812729172415175,\n              50.682176515374465\n            ],\n            [\n              6.87987514009842,\n              50.68272071401333\n            ]\n          ]\n        ],\n        \"type\": \"Polygon\"\n      }\n    }\n  ]\n}\n</code></pre> <p>Paste this in the appropriate settings menu.</p> <p>You can name the zone to help you remember what it encompasses. You can add multiple zones.</p> <p>Points that are within any of the privacy zones will not be shown in the share pictures. Except when all of the points are in the privacy zone, then all the points will be shown.</p>"},{"location":"features/upload/","title":"Uploading activities","text":"<p>Some users don't want to restart the application each time they add new activities but run it on their home server. For this use case you can upload activities. Uploading files is a potential security issue and it is protected with a password. This feature is only enabled when you have set a password in the configuration file.</p> <p>Put the following into your <code>config.json</code> file:</p> <pre><code>{\n    \"upload_password\": \"fb1c8d62-07a5-47bf-ada1-30aa66e41d8a\"\n}\n</code></pre> <p>Be sure to choose your own password and not use the one from this documentation.</p> <p>Then you can go to the upload page and see this form:</p> <p></p> <p>Select a file that you want to upload and a target directory within the \u201cActivities\u201d directory. Finally, enter the password from the configuration file.</p> <p>After you have uploaded the file, you will be redirected to the parsed activity.</p>"},{"location":"getting-started/advanced-metadata-extraction/","title":"Advanced Metadata extraction","text":"<p>If you would like to set the metadata fields or change what part of the filename should be the activity name, you can use a custom directory structure with corresponding regular expressions.</p> <p>An example directory structure:</p> <pre><code>Activities/\n\u251c\u2500 Ride/\n\u2502  \u251c\u2500 Trekking Bike/\n\u2502  \u2502  \u251c\u2500 2024-03-03-17-42-10 Home to Bakery.gpx\n\u251c\u2500 Hike/\n\u2502  \u251c\u2500 Hiking Boots 2019/\n\u2502  \u2502  \u251c\u2500 2024-03-03-11-03-18 Some nice place with Alice and Bob.fit\n</code></pre>"},{"location":"getting-started/advanced-metadata-extraction/#custom-regular-expressions","title":"Custom Regular expressions","text":"<p>The program uses regular expressions to search for patterns in the relative path (in Activities) and extracts the relevant parts with named capture groups <code>(?P&lt;kind&gt;)</code>, <code>(?P&lt;equipment&gt;)</code>, <code>(?P&lt;name&gt;)</code>.</p> <p>You can use python to test your regular expressions. Read the python re documentation for help.</p> <p><pre><code>import re\nre.search(r'(?P&lt;kind&gt;[^/]+)/(?P&lt;equipment&gt;[^/]+)/(?P&lt;name&gt;[^/.]+)', '/Ride/Trekking Bike/2024-03-03-17-42-10 Home to Bakery.gpx').groupdict()\n</code></pre> <pre><code>{'kind': 'Ride', 'equipment': 'Trekking Bike', 'name': '2024-03-03-17-42-10 Home to Bakery'}\n</code></pre></p> <p>You can add your custom regular expressions under the <code>Admin</code> menu - <code>Settings</code> - <code>Metadata Extraction</code> in the WebUI. Settings are saved in your <code>Playground</code> directory.</p>"},{"location":"getting-started/advanced-metadata-extraction/#filename-as-name-simple","title":"Filename as Name (simple)","text":"<p>Path:</p> <pre><code>Activities/\n\u251c\u2500 Ride/\n\u2502  \u251c\u2500 Trekking Bike/\n\u2502  \u2502  \u251c\u2500 2024-03-03-17-42-10 Home to Bakery.gpx\n</code></pre> <pre><code>(?P&lt;kind&gt;[^/]+)/(?P&lt;equipment&gt;[^/]+)/(?P&lt;name&gt;[^/.]+)\n</code></pre> <ul> <li>kind: <code>Ride</code></li> <li>equipment: <code>Trekking Bike</code></li> <li>name: <code>2024-03-03-17-42-10 Home to Bakery</code></li> </ul>"},{"location":"getting-started/advanced-metadata-extraction/#filename-without-date-as-name-useful-for-osmand-naming","title":"Filename without date as Name (useful for OsmAnd naming)","text":"<p>Path:</p> <pre><code>Activities/\n\u251c\u2500 Ride/\n\u2502  \u251c\u2500 Trekking Bike/\n\u2502  \u2502  \u251c\u2500 2024-03-03-17-42-10 Home to Bakery.gpx\n\u2502  \u2502  \u251c\u2500 2024-03-04-16-52-26.gpx\n\u2502  \u2502  \u251c\u2500 2024-04-21_10-28_Sun OsmAnd default track.gpx\n\u2502  \u2502  \u251c\u2500 2024-04-22_07-55_Mon.gpx\n</code></pre> <pre><code>(?P&lt;kind&gt;[^/]+)/(?P&lt;equipment&gt;[^/]+)/[-\\d_ ]+(?P&lt;name&gt;[^/]+)(?:\\.\\w+)+$\n</code></pre> <ul> <li>kind: <code>Ride</code></li> <li>equipment: <code>Trekking Bike</code></li> <li>names: <code>Home to Bakery</code> ; <code></code> ; <code>Sun OsmAnd default track</code> ; <code>Mon</code></li> </ul> <p>Attention, name may be empty if it is not included in the file name. For OsmAnd default naming the weekday is included in the name.</p>"},{"location":"getting-started/advanced-metadata-extraction/#filename-after-first-space-as-name","title":"Filename after first space as Name","text":"<p>Path:</p> <pre><code>Activities/\n\u251c\u2500 Ride/\n\u2502  \u251c\u2500 Trekking Bike/\n\u2502  \u2502  \u251c\u2500 2024-03-03-17-42-10 Home to Bakery.gpx\n\u2502  \u2502  \u251c\u2500 2024-04-22_07-55_Mon.gpx\n\u2502  \u2502  \u251c\u2500 2024-04-21_10-28_Sun OsmAnd default track.gpx\n</code></pre> <pre><code>(?P&lt;kind&gt;[^/]+)/(?P&lt;equipment&gt;[^/]+)/\\S+ ?(?P&lt;name&gt;[^/\\.]*)\n</code></pre> <ul> <li>kind: <code>Ride</code></li> <li>equipment: <code>Trekking Bike</code></li> <li>names: <code>Home to Bakery</code> ; <code></code> ; <code>OsmAnd default track</code></li> </ul> <p>Attention, name may be empty if it is not included in the file name (also for OsmAnd default naming).</p>"},{"location":"getting-started/advanced-metadata-extraction/#grouping-activity-files-under-a-common-name-for-example-all-your-commutes","title":"Grouping activity files under a common name, for example all your commutes","text":"<p>Path:</p> <pre><code>Activities/\n\u251c\u2500 Ride/\n\u2502  \u251c\u2500 Trekking Bike/\n\u2502  \u2502  \u251c\u2500 Commute/\n\u2502  \u2502  \u2502  \u251c\u2500 2024-03-04-07-06-12.gpx\n\u2502  \u2502  \u2502  \u251c\u2500 2024-03-04-15-42-32.gpx\n</code></pre> <pre><code>(?P&lt;kind&gt;[^/]+)/(?P&lt;equipment&gt;[^/]+)/(?P&lt;name&gt;[^/]+)/\n</code></pre> <ul> <li>kind: <code>Ride</code></li> <li>equipment: <code>Trekking Bike</code></li> <li>name: <code>Commute</code> (for all activities in Commute directory )</li> </ul>"},{"location":"getting-started/advanced-metadata-extraction/#activities-without-equipment","title":"Activities without equipment","text":"<p>Path:</p> <pre><code>Activities/\n\u251c\u2500 Run/\n\u2502  \u251c\u2500 2024-03-09-09-24-03 To the lake.gpx\n\u2502  \u251c\u2500 2024-03-10-09-44-37 To the top of the hill.gpx\n</code></pre> <pre><code>(?P&lt;kind&gt;[^/]+)/[-\\d_ ]+(?P&lt;name&gt;[^/]+)(?:\\.\\w+)+$\n</code></pre> <ul> <li>kind: <code>Run</code></li> <li>equipment: <code>Unknown</code></li> <li>names: <code>To the lake</code> ; <code>To the top of the hill</code></li> </ul>"},{"location":"getting-started/advanced-metadata-extraction/#next-steps","title":"Next Steps","text":"<p>If you you manually rename, move or delete your activity files, the program needs to reload to respect these changes. You can restart the program or visit <code>Scan New Activities</code> in the admin menu of the WebUI.</p>"},{"location":"getting-started/docker-compose-tailscale/","title":"Using Git Version via Docker Compose and Tailscale VPN","text":"<p>Docker is a software that allows you to run Linux programs in a container. Docker Compose is a tool for defining multi-container Docker environments in a single YAML configuration file and deploy it with a single command.</p> <p>Tailscale is a VPN solution based on the Wireguard protocol which lets you connect all devices within your virtual private network (tailnet). The Tailscale Docker container exposes the services only via a direct VPN connection, which avoids exposing ports to the open internet to connect to your geo-activity-playground instance on-the-go. It provides a domain with a valid Let's Encrypt certificate which is only accessible via the tailnet. The configuration is based on Docker Tailscale Guide.</p> <p>This how-to will give you an example <code>compose.yml</code> that can build the geo-activity-playground docker image from Github and start this project within a Docker container and connecting it via Tailscale.</p>"},{"location":"getting-started/docker-compose-tailscale/#tailscale-prerequisites","title":"Tailscale Prerequisites","text":"<ul> <li>Active account</li> <li>Enabled MagicDNS (in DNS section of admin console)</li> <li>Enabled HTTPS (in DNS section of admin console)</li> <li>Auth-Key</li> <li>ACL policy for tag</li> </ul>"},{"location":"getting-started/docker-compose-tailscale/#create-auth-key-and-acl-policy-for-tag","title":"Create Auth-Key and ACL policy for tag","text":"<p>More information on generating auth keys Navigate to https://login.tailscale.com/admin/settings/keys and generate an auth key.</p> <p>Example Auth-Key configuration: - Description: docker - Reusable: yes - Expiration: 7 days - Ephemeral: No - Tags: tag:container</p> <p>In order to use the tag, it must first be defined in your Access control policy in the admin console. Set the same tag as in the Auth-Key.</p> <pre><code>\"tagOwners\": {\n    \"tag:container\": [\"autogroup:admin\"],\n},\n</code></pre> <p>When you apply a tag to a device for the first time and authenticate it, the tagged device's key expiry is disabled by default.</p>"},{"location":"getting-started/docker-compose-tailscale/#preparing-tailscale-configuration","title":"Preparing Tailscale configuration","text":"<p>The geo-activity-playground service will be made available by using the Tailscale Serve functionality. It routes traffic from other devices on your Tailscale network (known as a tailnet) to a local service, in this case inside the container. It creates a reverse proxy to the geo-activity-playground container internal port 5000 (do not change it). <code>TS_CERT_DOMAIN</code> is comprised of a subdomain (hostname set in the <code>compose.yml</code>) and the tailnet root domain.</p> <pre><code>mkdir -p /docker/geo-activity-playground/{ts-state,ts-config}\ncd /docker/geo-activity-playground/ts-config\nnano geo-activity-playground.json\n</code></pre> <pre><code>{\n  \"TCP\": {\n    \"443\": {\n      \"HTTPS\": true\n    }\n  },\n  \"Web\": {\n    \"${TS_CERT_DOMAIN}:443\": {\n      \"Handlers\": {\n        \"/\": {\n          \"Proxy\": \"http://127.0.0.1:5000\"\n        }\n      }\n    }\n  }\n}\n</code></pre>"},{"location":"getting-started/docker-compose-tailscale/#compose-configuration-with-tailscale-network","title":"Compose configuration with Tailscale network","text":"<p>With these steps the playground folder (which contains the activities) will be located in the docker project folder. The location can be changed in the <code>compose.yml</code>.</p> <pre><code>mkdir -p /docker/geo-activity-playground/playground/Activities\ncd /docker/geo-activity-playground\nnano compose.yml\n</code></pre> <pre><code>services:\n  ts-geo-activity-playground:\n    image: tailscale/tailscale:latest\n    container_name: ts-geo-activity-playground\n    hostname: geo-activity-playground # set your desired name, which will be the tailscale subdomain\n    environment:\n      - TS_AUTHKEY=tskey-auth-yyyyyyyyyyyyyyyyyyyyyyyyyyyy # paste your created Auth-Key\n      - TS_EXTRA_ARGS=--advertise-tags=tag:container # set the same tag as in the Auth-Key\n      - TS_SERVE_CONFIG=/config/geo-activity-playground.json\n      - TS_STATE_DIR=/var/lib/tailscale\n    volumes:\n      - /docker/geo-activity-playground/ts-state:/var/lib/tailscale\n      - /docker/geo-activity-playground/ts-config:/config\n      - /dev/net/tun:/dev/net/tun\n    cap_add:\n      - net_admin\n      - sys_module\n    restart: unless-stopped\n  geo-activity:\n    build:\n      context: https://github.com/martin-ueding/geo-activity-playground.git\n      # this sets the build context to the DOCKERFILE located in the Github repository\n    container_name: geo-activity-playground\n    depends_on:\n      - ts-geo-activity-playground # start container after the VPN network is active\n    network_mode: service:ts-geo-activity-playground # link container network to tailscale container\n    volumes:\n      - /docker/geo-activity-playground/playground:/data # optional: change left side to your desired playground directory\n    restart: unless-stopped\n</code></pre> <p>If you want to build the release version of geo-activity-playground from Github instead, you can adjust the build context and add the release tag. <code>context: https://github.com/martin-ueding/geo-activity-playground.git#0.29.1</code></p>"},{"location":"getting-started/docker-compose-tailscale/#building-image-and-running-container","title":"Building image and running container","text":"<p>You need to set up your files according to one of the presented methods, like activity files or the Strava API. Consult the other pages in the sidebar for the details.</p> <p>Once you have your playground directory, you can build the image and start the container.</p> <pre><code>docker compose build\ndocker compose up -d\n</code></pre> <p>This will start the webserver and expose it via your tailnet on <code>https://[HOSTNAME].[YourTailnetName].ts.net/</code>, eg. <code>https://geo-activity-playground.tail41a3.ts.net/</code>. In order to access your instance via that domain, you have to install and authenticate the Tailscale client app on your device you want to open it from.</p>"},{"location":"getting-started/docker-compose-tailscale/#updating-the-image","title":"Updating the image","text":"<p>If using the tagged release version of geo-activity-playground, update the tag to the latest one first.</p> <pre><code>docker compose down\ndocker compose build\ndocker compose up -d --force-recreate\n</code></pre>"},{"location":"getting-started/docker-compose/","title":"Using Git Version via Docker Compose","text":"<p>Docker is a software that allows you to run Linux programs in a container. Docker Compose is a tool for defining multi-container Docker environments in a single YAML configuration file and deploy it with a single command.</p> <p>This how-to will give you an example <code>compose.yml</code> that can build the geo-activity-playground docker image from Github and start this project within a Docker container.</p>"},{"location":"getting-started/docker-compose/#creating-directory-structure-and-composeyml","title":"Creating directory structure and compose.yml","text":"<p>With these steps the playground folder (which contains the activities) will be located in the docker project folder. The location can be changed in the <code>compose.yml</code>.</p> <pre><code>mkdir -p /docker/geo-activity-playground/playground/Activities\ncd /docker/geo-activity-playground\nnano compose.yml\n</code></pre> <pre><code>services:\n  geo-activity:\n    build:\n      context: https://github.com/martin-ueding/geo-activity-playground.git\n      # this sets the build context to the DOCKERFILE located in the Github repository\n    container_name: geo-activity-playground\n    volumes:\n      - /docker/geo-activity-playground/playground:/data  # optional: change left side to your desired playground directory\n    ports:\n      - 5000:5000 # optional: change the exposed port on the left side\n    restart: unless-stopped\n</code></pre> <p>If you want to build the release version from Github instead, you can adjust the build context and add the release tag. <code>context: https://github.com/martin-ueding/geo-activity-playground.git#0.29.1</code></p>"},{"location":"getting-started/docker-compose/#building-image-and-running-container","title":"Building image and running container","text":"<p>You need to set up your files according to one of the presented methods, like activity files or the Strava API. Consult the other pages in the sidebar for the details.</p> <p>Once you have your playground directory, you can build the image and start the container.</p> <pre><code>docker compose build\ndocker compose up -d\n</code></pre> <p>This will start the webserver on http://localhost:5000/ or at the port you chose to expose.</p> <p>Note that port 5000 may not be available on macOS because of AirPlay, so you can map to another port.</p>"},{"location":"getting-started/docker-compose/#updating-the-image","title":"Updating the image","text":"<p>If using the tagged release version, update the tag to the latest one first.</p> <pre><code>docker compose down\ndocker compose build\ndocker compose up -d --force-recreate\n</code></pre>"},{"location":"getting-started/docker/","title":"Using Git Version via Docker","text":"<p>Docker is a software that allows you to run Linux programs in a container. This how-to will show you how to build and start this project within a Docker container.</p>"},{"location":"getting-started/docker/#build-the-image","title":"Build the image","text":"<p>First you need to build the Docker image. For this download the source code and build the image using the following commands:</p> <pre><code>git clone https://github.com/martin-ueding/geo-activity-playground.git\ncd geo-activity-playground\nsudo docker build -t geo-activity-playground .\n</code></pre> <p>Perhaps you do not need <code>sudo</code> on your system.</p>"},{"location":"getting-started/docker/#run-the-image","title":"Run the image","text":"<p>You need to set up your files according to one of the presented methods, like activity files or the Strava API. Consult the other pages in the sidebar for the details.</p> <p>Once you have your playground directory, you can launch the Docker image with the following. Be sure to replace <code>path/to/playground</code> with your path.</p> <pre><code>sudo docker run -p 5000:5000 -v path/to/playground:/data -it geo-activity-playground\n</code></pre> <p>This will start the webserver on http://localhost:5000/.</p> <p>Note that port 5000 may not be available on macOS because of AirPlay, so you can map to another port by replacing the port specifier from above with <code>-p 8000:5000</code>. Then you can open http://localhost:8000/ in your browser.</p>"},{"location":"getting-started/installing-git-on-linux/","title":"Installing Git Version On Linux","text":"<p>As this project is still in development, you might want to have a peek into the development version. This is more advanced than using the stable versions, but not impossibly hard.</p> <p>First you need to clone the git repository from GitHub using the following command:</p> <pre><code>git clone https://github.com/martin-ueding/geo-activity-playground.git\n</code></pre> <p>That will create a directory <code>geo-activity-playground</code> in your current working directory.</p> <p>Then change into that directory:</p> <pre><code>cd geo-activity-playground\n</code></pre> <p>Next we will use Poetry to install the dependencies of the project. First you need to make sure that you have Poetry available. On Ubuntu/Debian run <code>sudo apt install python3-poetry</code>, on Fedora/RedHat run <code>sudo dnf install poetry</code> to install it.</p> <p>Then we can create the virtual environment:</p> <pre><code>poetry install\n</code></pre> <p>And next we can run the program:</p> <pre><code>poetry run geo-activity-playground --basedir path/to/your/playground --help\n</code></pre> <p>Replace the <code>--help</code> with the subcommands described in the help message or the other parts described this documentation.</p> <p>You will need the <code>--basedir</code> option because you run the program from the source directory and not from your playground directory. If you install the stable version via PIP as described in the other page, you will not need this option.</p>"},{"location":"getting-started/installing-git-on-linux/#updating-to-the-latest-version","title":"Updating to the latest version","text":"<p>Over time I will add more commits to the source control system. In order to update your clone to the latest version, execute the following:</p> <pre><code>git pull\n</code></pre> <p>This will download the missing changesets and apply them to your downloaded version. After that is done, you need to update your virtual environment with this:</p> <pre><code>poetry install\n</code></pre> <p>And then you can continue using it as before.</p>"},{"location":"getting-started/installing-stable-on-linux/","title":"Installing Stable On Linux","text":"<p>In this how-to guide I will show you how you can install the latest stable version of this project on Linux.</p>"},{"location":"getting-started/installing-stable-on-linux/#pipx-method","title":"PIPX method","text":"<p>The ideal way to install this project, is using <code>pipx</code>. First ensure that you have it installed:</p> Distribution Command Ubuntu, Debian <code>sudo apt install pipx</code> Fedora, RedHat <code>sudo dnf install pipx</code> Arch, Manjaro <code>sudo pacman -Syu python-pipx</code> <p>Using PIPX, you can then install the latest version using this command:</p> <pre><code>pipx install geo-activity-playground\n</code></pre> <p>That should be it. You might need to ensure that the <code>$PATH</code> is correct. For that see the section below.</p>"},{"location":"getting-started/installing-stable-on-linux/#pip-method","title":"PIP method","text":"<p>If you don't want to use PIPX, you can also use regular PIP. First install PIP:</p> Distribution Command Ubuntu, Debian <code>sudo apt install python3-pip</code> Fedora, RedHat <code>sudo dnf install python3-pip</code> Arch, Manjaro <code>sudo dnf install python-pip</code> <p>Then install the package into your user directory.</p> <pre><code>pip install --user geo-activity-playground\n</code></pre> <p>That should be it. You might need to ensure that the <code>$PATH</code> is correct. For that see the section below.</p>"},{"location":"getting-started/installing-stable-on-linux/#ensure-that-the-path-is-correct","title":"Ensure that the PATH is correct","text":"<p>Next you can try to start the program by just entering the following into the terminal:</p> <pre><code>geo-activity-playground --help\n</code></pre> <p>If you get a help message, everything is fine. If you get an error about command not found, we need to adjust your PATH. Execute the following in your command line:</p> <pre><code>xdg-open ~/.profile\n</code></pre> <p>This brings up an editor with your shell profile. Add a line containing the following at the end of the file:</p> <pre><code>PATH=$PATH:$HOME/.local/bin\n</code></pre> <p>This adds the path to your shell environment. This becomes active after you log in again. In order to apply it also to your current shell session, execute <code>export PATH=$PATH:$HOME/.local/bin</code> in the terminal window. Try the first command in this section again, you should see the help message now.</p>"},{"location":"getting-started/installing-stable-on-linux/#upgrading-to-the-latest-version","title":"Upgrading to the latest version","text":"<p>At some later point you likely want to upgrade to the latest version. For this use this command if you used PIPX:</p> <pre><code>pipx upgrade geo-activity-playground\n</code></pre> <p>If you used PIP, use this:</p> <pre><code>pip install --user --upgrade geo-activity-playground\n</code></pre>"},{"location":"getting-started/installing-stable-on-windows/","title":"Installing Stable on Windows","text":"<p>This how-to will show you the installation of the project on Windows. Here in the guide we use Windows 10 with the locale set to German, it should generalize to Windows 11 as well.</p>"},{"location":"getting-started/installing-stable-on-windows/#installing-python","title":"Installing Python","text":"<p>First we need to install Python because that doesn't ship with Windows. Fortunately we can get it from the Microsoft Store. Open that via the start menu and you should see something like this:</p> <p></p> <p>Type \u201cPython\u201d into the search bar at the top. In the search results you likely see different Python versions like 3.11 and 3.10. The project is compatible with 3.10 to 3.12; I'd suggest to just go with 3.12. In case that you have already installed one of the other compatible versions, you can skip this step.</p> <p>Here we select Python 3.11.</p> <p></p> <p>In the top right there is a blue button to install the software. Click that.</p>"},{"location":"getting-started/installing-stable-on-windows/#installing-the-project","title":"Installing the project","text":"<p>After that has run through, you need to open the Power Shell via the start menu. It should open a command line window like this:</p> <p></p> <p>We can verify that Python is working by entering <code>python --version</code> and <code>pip --version</code>. It should give a sensible version message like this:</p> <p></p> <p>Then we can ues PIP to install the project. Type the following:</p> <pre><code>pip install -U geo-activity-playground\n</code></pre> <p>It should look like this:</p> <p></p> <p>Then press Enter and it will install it, looking like this:</p> <p></p> <p>That might take a while. After that has run through, it should give a success message:</p> <p></p> <p>Then we're done with this window, you can close it now.</p>"},{"location":"getting-started/installing-stable-on-windows/#putting-your-activity-files-in-place","title":"Putting your activity files in place","text":"<p>Next you need to create a folder to put the files. I've placed mine just into the Documents folder. In there I've created a folder named exactly \u201cActivities\u201d.</p> <p></p> <p>Inside this folder there are my GPX/FIT/TCX/KML files as outlined in how-to guide on using activity files.</p> <p></p> <p>You need to have at least one activity file before you can start the program.</p>"},{"location":"getting-started/installing-stable-on-windows/#starting-the-webserver","title":"Starting the webserver","text":"<p>Once you have your activity files in place, we need to add a start script. Right-click into the playground folder (next to the \u201cActivities folder\u201d) and in the context menu select \u201cCreate New\u201d and then \u201cText File\u201d. Name it <code>start.bat</code>. Windows will ask you whether want to change the suffix (file extension) because it might get unusable. Yes, we want to do that. It should look like this:</p> <p></p> <p>Then right-click on that file and select \u201cEdit\u201d. A text editor will open up. Put the following content into this file:</p> <pre><code>python -m geo_activity_playground serve\npause\n</code></pre> <p>Then save and close it. I need you to create this file yourself and cannot offer a download because the Windows Defender will not allow you to execute such script files downloaded as a security precaution. If you create the file yourself, it will let you execute it.</p> <p>Once you have the <code>start.bat</code> there, you can double-click on it to execute it. A new terminal window should open and it should start to parse your activities.</p> <p></p> <p>After it has loaded everything, you can open http://127.0.0.1:5000/ in your browser. You should then see the landing page:</p> <p></p> <p>Also other functions like the heatmap work:</p> <p></p> <p>That's it, have fun!</p>"},{"location":"getting-started/moving-from-strava/","title":"Moving from Strava","text":"<p>If you have been using Strava up to this point but want to use this project from now on, this is the correct guide. Here I will show how you can convert your data from Strava into the format of this project and keep adding new data without Strava in the future.</p>"},{"location":"getting-started/moving-from-strava/#download-your-archive-from-strava","title":"Download your archive from Strava","text":"<p>Go to the Strava account download page and request a download of your data. This will take a while and you get a notification via e-mail when it is done.</p> <p>Once it has run through, you will be able to download a ZIP file. Once extracted, it will have a structure like this:</p> <pre><code>.\n\u251c\u2500\u2500 activities  [2217 entries exceeds filelimit, not opening dir]\n\u251c\u2500\u2500 activities.csv\n\u251c\u2500\u2500 applications.csv\n\u251c\u2500\u2500 bikes.csv\n\u251c\u2500\u2500 blocks.csv\n\u251c\u2500\u2500 categories_of_personal_information_we_collect.pdf\n\u251c\u2500\u2500 clubs\n\u251c\u2500\u2500 clubs.csv\n\u251c\u2500\u2500 comments.csv\n\u251c\u2500\u2500 community_content.json\n\u251c\u2500\u2500 community_personal_data.json\n\u251c\u2500\u2500 components.csv\n\u251c\u2500\u2500 connected_apps.csv\n\u251c\u2500\u2500 contacts.csv\n\u251c\u2500\u2500 email_preferences.csv\n\u251c\u2500\u2500 events.csv\n\u251c\u2500\u2500 favorites.csv\n\u251c\u2500\u2500 flags.csv\n\u251c\u2500\u2500 followers.csv\n\u251c\u2500\u2500 following.csv\n\u251c\u2500\u2500 general_preferences.csv\n\u251c\u2500\u2500 global_challenges.csv\n\u251c\u2500\u2500 goals.csv\n\u251c\u2500\u2500 group_challenges.csv\n\u251c\u2500\u2500 information_we_disclose_for_a_business_purpose.pdf\n\u251c\u2500\u2500 local_legend_segments.csv\n\u251c\u2500\u2500 logins.csv\n\u251c\u2500\u2500 media  [252 entries exceeds filelimit, not opening dir]\n\u251c\u2500\u2500 media.csv\n\u251c\u2500\u2500 memberships.csv\n\u251c\u2500\u2500 messaging.json\n\u251c\u2500\u2500 metering.csv\n\u251c\u2500\u2500 mobile_device_identifiers.csv\n\u251c\u2500\u2500 orders.csv\n\u251c\u2500\u2500 partner_opt_outs.csv\n\u251c\u2500\u2500 posts.csv\n\u251c\u2500\u2500 privacy_zones.csv\n\u251c\u2500\u2500 profile.csv\n\u251c\u2500\u2500 profile.jpg\n\u251c\u2500\u2500 reactions.csv\n\u251c\u2500\u2500 routes\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 1.gpx\n\u251c\u2500\u2500 routes.csv\n\u251c\u2500\u2500 segments.csv\n\u251c\u2500\u2500 shoes.csv\n\u251c\u2500\u2500 social_settings.csv\n\u251c\u2500\u2500 starred_routes.csv\n\u251c\u2500\u2500 starred_segments.csv\n\u251c\u2500\u2500 support_tickets.csv\n\u2514\u2500\u2500 visibility_settings.csv\n</code></pre> <p>This directory contains a file <code>activities.csv</code> with the metadata and also a directory <code>activities</code> with the files that you have recorded.</p>"},{"location":"getting-started/moving-from-strava/#convert-your-checkout","title":"Convert your checkout","text":"<p>Use the following command to create a directory from your Strava actitivies:</p> <pre><code>geo-activity-playground convert-strava-checkout ~/Downloads/export_123456/ ~/Documents/Outdoors/Playground\n</code></pre> <p>This should read through all the activities and create a directory structure with the pattern <code>~/Documents/Outdoors/Playground/Activities/{Kind}/{Equipment}/{Commute}/{Date} {Time} {Name}.{Suffix}</code>. For instance one file might be named <code>Activities/Run/5212701.0/2019-07-09 09-59-25 Around the \u5317\u4eac\u5927\u5b66 campus.gpx.gz</code>.</p> <p>The equipment might have nonsensical seeming names like <code>10370891.0</code>. The problem here is that Strava doesn't export the list of activities with that index. If your equipment doesn't have a nickname, it will just be such a number.</p>"},{"location":"getting-started/moving-from-strava/#use-the-directory","title":"Use the directory","text":"<p>Now that the files from Strava are converted, consult the guide on using activity files to proceed from here.</p>"},{"location":"getting-started/moving-from-strava/#recording-more-activities","title":"Recording more activities","text":"<p>Now that you don't record via Strava, you will need some other app to record your activities. There are Apps like OsmAnd or OpenTracks which provide such functionality. Export the files as GPX, FIT, TCX or KML files and put them into the directory structure. On the next start of the program, they will be picked up.</p>"},{"location":"getting-started/starting-the-webserver/","title":"Starting The Webserver","text":"<p>Before you start here, you should have done these things:</p> <ul> <li>You have installed the program either from a stable version or from git.</li> <li>You have set up a playground with either activity files or the Strava API.</li> </ul> <p>Now we can start the webserver which provides most of the features. This is done with the <code>serve</code> command. So depending on how you have installed it, the commands could look like these:</p> <ul> <li><code>geo-activity-playground serve</code> if you are in the playground directory and have installed a stable version.</li> <li><code>geo-activity-playground --basedir ~/Dokumente/Karten/Playground serve</code> if your playground directory is somewhere else and you have installed a stable version.</li> <li><code>poetry run geo-activity-playground --basedir ~/Dokumente/Karten/Playground serve</code> if you have it from the git checkout and want to use local files in your directory as a data source.</li> </ul> <p>The webserver will start up and give you a bit of output like this:</p> <pre><code>2023-11-19 17:59:23 geo_activity_playground.importers.strava_api INFO Loading metadata file \u2026\n2023-11-19 17:59:23 stravalib.protocol.ApiV3 INFO GET 'https://www.strava.com/api/v3/athlete/activities' with params {'before': None, 'after': 1700392964, 'page': 1, 'per_page': 200}\n2023-11-19 17:59:23 geo_activity_playground.importers.strava_api INFO Checking for missing time series data \u2026\n * Serving Flask app 'geo_activity_playground.webui.app'\n * Debug mode: off\n2023-11-19 17:59:23 werkzeug INFO WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.\n * Running on http://127.0.0.1:5000\n2023-11-19 17:59:23 werkzeug INFO Press CTRL+C to quit\n</code></pre> <p>The warning about the development server is fine. We are using this only to play around, not to power a web service for other users.</p> <p>Open http://127.0.0.1:5000 to open the website in your browser. There might be some more messages about downloading and parsing data. The first startup will take quite some time. When it is done you will see something like this:</p> <p></p> <p>Click around and explore the various features.</p>"},{"location":"getting-started/starting-the-webserver/#setting-host-and-port","title":"Setting host and port","text":"<p>In case you don't like the default value of <code>127.0.0.1:5000</code>, you can use the optional command line arguments <code>--host</code> and <code>--port</code> to specify your values.</p>"},{"location":"getting-started/using-activity-files/","title":"Using Activity Files","text":"<p>Outdoor activities are usually recorded as <code>.GPX</code> or <code>.FIT</code> files. Some apps like OsmAnd , OpenTracks or Organic Maps, GPS handhelds, smartwatches or cycling computers give you these files.</p>"},{"location":"getting-started/using-activity-files/#supported-file-formats","title":"Supported file formats","text":"<ul> <li>FIT</li> <li>GPX</li> <li>TCX</li> <li>KML</li> <li>KMZ</li> <li>Simra CSV export</li> </ul>"},{"location":"getting-started/using-activity-files/#add-activity-files","title":"Add Activity Files","text":"<p>Before starting the service you need to create a folder for your activities and put at least one activity file in there.</p> <p>Create a <code>Playground</code> folder on your storage somewhere and add a subfolder <code>Activities</code>. There you can add your activity files. For example:</p> <pre><code>~/\n\u251c\u2500 Documents[or other location]/\n\u2502  \u251c\u2500 Playground/\n\u2502  \u2502  \u251c\u2500 Activities/\n\u2502  \u2502  \u2502  \u251c\u2500 2024-03-03-17-42-10 Home to Bakery.gpx\n</code></pre> <p>The program will treat the files as read-only and does not modify them.</p> <p>Once the service is running you can use the Uploader to add your files. You can manually rename, move or delete your activity files, but the program needs to reload to respect these changes. You can restart the program or visit <code>Scan New Activities</code> in the admin menu of the WebUI.</p>"},{"location":"getting-started/using-activity-files/#metadata-extraction","title":"Metadata extraction","text":"<p>Most activity file formats contain basic data like <code>date</code>, <code>time</code> and <code>track points</code>. Each activity in geo-activity-playground also has the metadata fields <code>kind</code>, <code>equipment</code> and <code>name</code>. They can be extracted from files that contain them.</p> <p>If no metadata is found, <code>kind</code> and <code>equipment</code> default to <code>Unknown</code>. The <code>name</code> is then extracted from the file name (without the suffix). So for <code>Activities/2024-03-03-17-42-10 Home to Bakery.gpx</code> the <code>name</code> is <code>2024-03-03-17-42-10 Home to Bakery</code>.</p>"},{"location":"getting-started/using-activity-files/#next-steps","title":"Next steps","text":"<p>Once you have your files put into the directory, you're all set and can proceed with the next steps.</p> <p>You can extend the directory structure to categorize your activities, see Advanced Metadata Extraction.</p>"},{"location":"getting-started/using-strava-api/","title":"Using Strava API","text":"<p>You might have all your data on the Strava service and would like to use this for additional analytics without moving your data. That is fine.</p> <p>If you don't mind a bit of rate-limiting, you can just directly go ahead and start the webserver. It will offer to connect with Strava.</p>"},{"location":"getting-started/using-strava-api/#your-own-strava-app","title":"Your own Strava App","text":"<p>In order to use the Strava API without sharing the rate-limiting with other users, you need to create your own app. If my explanation doesn't suit you, have a look at this how-to guide as well.</p> <p>Navigate to the API settings page and create an app. It only needs to have read permissions.</p> <p>After you are done with that, you can see your App here:</p> <p></p> <p>There is a \"client ID\" and a \"client secret\" that we are going to need for the next step. In general our app could be used by all sorts of people who can then access their data only. We want to access our own data, but we still need to authorize our app to use our data. </p> <p>Open the webserver of this program and go the Strava API setup page. Enter your client ID and client secret, click on \"Connect to Strava\".</p> <p>This will prompt an OAuth2 request where you have to grant permissions to your app. After that you will be redirected back to the app and it should be set up. At the moment you need to restart the webserver such that it can start to download the activities. Due to rate-limiting it can still take a while.</p>"},{"location":"getting-started/using-strava-api/#use-export-to-avoid-rate-limiting","title":"Use export to avoid rate limiting","text":"<p>When you first start this program and use the Strava API as a data source, it will download the metadata for all your activities. Then it will start to download all the time series data for each activity. Strava has a rate limiting, so after the first 200 activities it will crash and you will have to wait for 15 minutes until you can try again and it will download the next batch.</p> <p>Therefore it is recommended to use a Strava export in order to get started quicker. For this go to the Strava account download page and download all your data. You will get a ZIP file. Unpack the files into <code>Playground/Strava Export</code>. These will be picked up there. Activities from Strava will only be downloaded after importing all these, and only the ones after the last one in the export will be downloaded. This way you can get started much quicker.</p>"},{"location":"getting-started/using-strava-api/#skip-strava-download","title":"Skip Strava download","text":"<p>If you don't want to download new activities from Strava, use <code>--skip-reload</code> to have the webserver start right away.</p>"},{"location":"reference/changelog/","title":"Changelog","text":"<p>This is the log of high-level changes that I have done in the various versions.</p>"},{"location":"reference/changelog/#version-0","title":"Version 0","text":"<p>This is the pre-release series. Things haven't settled yet, so each minor version might introduce breaking changes.</p>"},{"location":"reference/changelog/#version-036","title":"Version 0.36","text":"<ul> <li>GH-212: Add date filter to heatmap.</li> <li>GH-209: Add square planner to navigation.</li> <li>GH-211: Clip speed coloring with IQR to remove outliers.</li> </ul> <p>Internal stuff:</p> <ul> <li>GH-206: Remove multiprocessing for parsing activities due to warnings about multithreading. This unfortunately slows down initial processing.</li> <li>GH-214: Start to simplify the controller structure.</li> <li>GH-213: Encode kinds via integers in heatmap to protect it against weird kind names containing control symbols.</li> </ul>"},{"location":"reference/changelog/#version-035","title":"Version 0.35","text":""},{"location":"reference/changelog/#version-0351","title":"Version 0.35.1","text":"<ul> <li>GH-208: Support activity files with uppercase suffix.</li> <li>Do some internal changes to the map background generation for share pictures.</li> <li>Do some refactoring in the web code.</li> </ul>"},{"location":"reference/changelog/#version-0350","title":"Version 0.35.0","text":"<ul> <li>Add button to explorer tile map to remove map background.</li> </ul>"},{"location":"reference/changelog/#version-034","title":"Version 0.34","text":""},{"location":"reference/changelog/#version-0342","title":"Version 0.34.2","text":"<ul> <li>Host another JavaScript asset locally.</li> </ul>"},{"location":"reference/changelog/#version-0341","title":"Version 0.34.1","text":"<ul> <li>Host all assets locally to avoid using CDNs.</li> </ul>"},{"location":"reference/changelog/#version-0340","title":"Version 0.34.0","text":"<ul> <li>GH-197: Enforce UTF-8 encoding when reading the <code>activities.csv</code> from the Strava export.</li> <li>GH-197: Make CSV header parsing a bit more robust.</li> <li>GH-201: Correct label for equipment \"kinds\" plot.</li> <li>GH-203: Fix documentation, remove <code>--skip-strava</code> and replace it with <code>--skip-reload</code>.</li> <li>GH-205: Fix mismatch between ISO week and regular year.</li> <li>GH-157: Add a share picture per day.</li> </ul>"},{"location":"reference/changelog/#version-033","title":"Version 0.33","text":""},{"location":"reference/changelog/#version-0334","title":"Version 0.33.4","text":"<ul> <li>Add compatibility for Python 3.13.</li> </ul>"},{"location":"reference/changelog/#version-0333","title":"Version 0.33.3","text":"<ul> <li>GH-200: Fix startup without any activities.</li> <li>Fix upload when there is no <code>Activities</code> directory.</li> </ul>"},{"location":"reference/changelog/#version-0332","title":"Version 0.33.2","text":"<ul> <li>GH-198: Fix explorer map. The problem was that VS Code auto-formatted the embedded JavaScript and created syntax errors.</li> </ul>"},{"location":"reference/changelog/#version-0331","title":"Version 0.33.1","text":"<ul> <li>GH-156: Fix little bug with <code>_meta</code>.</li> </ul>"},{"location":"reference/changelog/#version-0330","title":"Version 0.33.0","text":"<ul> <li>Make heatmap colormap configurable via web UI.</li> <li>GH-196: Make tile map URL configurable via configuration file.</li> <li>Make daily pulse plot per year in tabs.</li> </ul>"},{"location":"reference/changelog/#version-0320","title":"Version 0.32.0","text":"<ul> <li>GH-173: Add config option <code>ignore_suffixes</code> which can be set to something like <code>[\".kml\"]</code> to ignore certain file types.</li> <li>Include all activities in the summary, even those which are not to be considered for achievements.</li> <li>Remove debug print.</li> <li>Make share picture always the same size independent of the content.</li> </ul>"},{"location":"reference/changelog/#version-0310","title":"Version 0.31.0","text":"<ul> <li>GH-189: Fix heatmap tile cache expiry in cases where the activity kind has changed.</li> <li>Make date and time formats better to read.</li> <li>GH-156: Add metadata editing functionality with override files.</li> </ul>"},{"location":"reference/changelog/#version-0300","title":"Version 0.30.0","text":"<ul> <li>GH-187: Update favicon to new logo.</li> <li>GH-174: Add new search functionality that also serves as an overview over all activities.</li> <li>GH-168: Clicking on table headers will sort the tables now.</li> <li>GH-162: Make track segmentation configurable with a configuration setting.</li> <li>Visualize cadence on the activity page.</li> <li>GH-188: Remove <code>root=</code> prefix in activity kind when importing from Strava.</li> <li>GH-188: Add option to rename activity kinds.</li> </ul>"},{"location":"reference/changelog/#version-029","title":"Version 0.29","text":""},{"location":"reference/changelog/#version-0292","title":"Version 0.29.2","text":"<ul> <li>Documentation improvements by beautiful-orca: GH-180, GH-181, GH-182, GH-183, GH-185</li> <li>GH-184: Use Python 3.12 in Docker.</li> <li>GH-178: Fix display of number of new tiles in activity view.</li> <li>GH-177: Fix distance from new <code>stravalib</code> version.</li> <li>GH-179: Work around Pandas deprecation message.</li> <li>GH-176: Do not modify filename on upload any more.</li> <li>GH-175: Mention Organic Maps.</li> </ul>"},{"location":"reference/changelog/#version-0291","title":"Version 0.29.1","text":"<ul> <li>GH-167: Fix explorer tile export.</li> <li>GH-169: Fix import of KML files with waypoints.</li> </ul>"},{"location":"reference/changelog/#version-0290","title":"Version 0.29.0","text":"<ul> <li>Use dropdown menus to make navigation a bit smaller.</li> <li>GH-163: Recompute explorer tiles when there are deleted activities. Previously this would lead to <code>KeyError</code> when trying to use the heatmap or the explorer tile maps.</li> <li>GH-161: Fix explorer tile clusters and square if one has activities that are not to be considered for achievements.</li> <li>GH-164: Create new function to handle write-and-replace on Windows.</li> <li>GH-155: Use the same scale for all plots with kind, make this configurable in the settings menu.</li> <li>Rewrite the documentation start page to make it more appealing and reflect the work in the web interface.</li> <li>GH-166: Add map with new explorer tiles to activity view.</li> <li>GH-160: Update version of <code>stravalib</code> and with that also <code>pydantic</code>. That fixes a bug with <code>recursive_guard</code>.</li> </ul>"},{"location":"reference/changelog/#version-028","title":"Version 0.28","text":"<ul> <li>Add settings menu to suppress fields from share pictures.</li> <li>Fix spelling mistake in navigation bar.</li> <li>Accelerate the tile visit computation.</li> <li>Ignore equipment offsets of equipments that don't exist.</li> <li>Reset corrupt heatmap cache files.</li> <li>GH-159: Improve password mechanism to protect both upload and settings.</li> <li>Document the use of Open Street Map uMap for missing explorer tiles on the go.</li> </ul>"},{"location":"reference/changelog/#version-027","title":"Version 0.27","text":""},{"location":"reference/changelog/#version-0271","title":"Version 0.27.1","text":"<ul> <li>Fix <code>num_processes</code> option.</li> </ul>"},{"location":"reference/changelog/#version-0270","title":"Version 0.27.0","text":"<ul> <li>GH-128: Let the Strava Checkout importer set the file <code>strava-last-activity-date.json</code> which is needed such that the Strava API importer can pick up after all the activities that have been imported via the checkout.</li> <li>GH-143: Use custom CSV parser to read activities that have newlines in their descriptions.</li> <li>GH-146: Make multiprocessing optional with <code>num_processes = 1</code> in the configuration.</li> <li>GH-147: Add another safeguard against activities that don't have latitude/longitude data.</li> <li>GH-149: Only pre-compute explorer maps for zoom 14 and 17 by default. Other ones just have to be enabled once. This saves a bit of computing time for most people that don't need to go down to zoom 19.</li> <li>GH-151: Do not fail if version cannot be determined.</li> <li>Add settings menu where one can configure various things:</li> <li>Equipment offsets</li> <li>Maximum heart rate for heart rate zones</li> <li>Metadata extractions from paths</li> <li>Privacy zones</li> <li>Strava connection</li> <li>The <code>config.json</code> replaces the <code>config.toml</code> and will automatically be generated.</li> <li>Fix bug in explorer tile interpolation that likely doesn't have an effect in practice.</li> </ul>"},{"location":"reference/changelog/#version-026","title":"Version 0.26","text":""},{"location":"reference/changelog/#version-0263","title":"Version 0.26.3","text":"<ul> <li>GH-142: Require <code>pandas &gt;= 2.2.0</code> to make sure that it knows about <code>include_groups</code>.</li> <li>GH-144: Ignore activities without time series when using the Strava Checkout import.</li> </ul>"},{"location":"reference/changelog/#version-0262","title":"Version 0.26.2","text":"<ul> <li>Start with a test suite for the web server that also tests importing.</li> <li>Already fixed a few little bugs with that.</li> <li>GH-141: Fix summary page if there are no activities with steps.</li> </ul>"},{"location":"reference/changelog/#version-0261","title":"Version 0.26.1","text":"<ul> <li>GH-139, GH-140: More fixes for Strava archive importer.</li> </ul>"},{"location":"reference/changelog/#version-0260","title":"Version 0.26.0","text":"<ul> <li>Add automatic dark mode.</li> <li>Add some more explanation for the Strava connection.</li> <li>GH-138: Fix import from Strava archive that was broken in 0.25.0.</li> <li>Style the settings page a bit.</li> </ul>"},{"location":"reference/changelog/#version-025","title":"Version 0.25","text":"<ul> <li>Restructure the way that activities are imported to realize a couple of benefits:</li> <li>Deleting activities is detected now, they are removed from the heatmap.</li> <li>If the code is changed, not everything has to be parsed again. This is especially helpful with regard to the rate-limited Strava API.</li> <li>Some code is deduplicated that had accumulated between activity file parsing and the Strava API.</li> <li>Unfortunately it means that everything needs to parsed again into the new format. I'm sorry about that, especially to you Strava users that need to deal with the rate limiting!</li> <li> <p>Add an web interface to connect to Strava API using a shared application such that it becomes much simpler to set up.</p> </li> <li> <p>GH-41: Compute moving time.</p> </li> <li>GH-127: Make calories and steps optional for the share picture.</li> <li>GH-131: Update to the column names in the Strava export.</li> <li>GH-133: Cope with manually recorded activities in Strava export.</li> <li>GH-134: Cope with broken FIT files.</li> </ul>"},{"location":"reference/changelog/#version-024","title":"Version 0.24","text":""},{"location":"reference/changelog/#version-0242","title":"Version 0.24.2","text":"<ul> <li>GH-127: Make calories and steps optional for the summary statistics.</li> </ul>"},{"location":"reference/changelog/#version-0241","title":"Version 0.24.1","text":"<ul> <li>GH-124: Add more timezone handling for Strava API.</li> <li>GH-125: Fix building of Docker container.</li> <li>GH-126: Fix heatmap download.</li> </ul>"},{"location":"reference/changelog/#version-0240","title":"Version 0.24.0","text":"<ul> <li>GH-43: Added nicer share pictures and privacy zones.</li> <li>GH-95: Display the number of new explorer tiles and squadratinhos per activity.</li> <li>GH-113: Open footer links in a new tab.</li> <li>GH-114: Show total distance and duration in day overview.</li> <li>GH-115: Add more summary statistics and add a \"hall of fame\" as well.</li> <li>GH-161: Show table for Eddington number, also update the plot to make it a bit easier to read. Add some more explanatory text.</li> <li>GH-118: Fix links in search results.</li> <li>GH-121: Fix link to share picture.</li> <li>GH-122: Convert everything to \"timezone naive\" dates in order to get rid of inconsistencies.</li> <li>GH-123: Fix startup from empty cache. A cache migration assumed that <code>activities.parquet</code> exists. I've added a check.</li> <li>Use Flask Blueprints to organize code.</li> <li>Remove half-finished \"locations\" feature from the navigation.</li> <li>Allow filtering the heatmap by activity kinds.</li> <li>Remove duplicate link to landing page from navigation.</li> </ul>"},{"location":"reference/changelog/#version-023","title":"Version 0.23","text":"<ul> <li>GH-111: Add password protection for upload.</li> <li>Use Flask \u201cflash\u201d messages.</li> <li>GH-110: Support routes that don't have time information attached them. That might be useful if you haven't recorded some particular track but still want it to count towards your heatmap and explorer tiles.</li> </ul>"},{"location":"reference/changelog/#version-022","title":"Version 0.22","text":"<ul> <li>GH-111: Allow uploading files from within the web UI and parse them directly after uploading.</li> <li>Fix bug that lead to re-parsing of activity files during startup.</li> </ul>"},{"location":"reference/changelog/#version-021","title":"Version 0.21","text":""},{"location":"reference/changelog/#version-0212","title":"Version 0.21.2","text":"<ul> <li>Fix crash in search due to missing <code>distance/km</code>.</li> </ul>"},{"location":"reference/changelog/#version-0211","title":"Version 0.21.1","text":"<ul> <li>Add support for Python 3.12.</li> </ul>"},{"location":"reference/changelog/#version-0210","title":"Version 0.21.0","text":"<ul> <li> <p>Breaking change: New way to extract metadata from paths and filenames. This uses regular expressions and is more versatile than the heuristic before. If you have used <code>prefer_metadata_from_file</code> before, see the documentation on activity files for the new way.</p> </li> <li> <p>GH-105: Ignore similar activities that have vanished.</p> </li> <li>GH-106: Be more strict when identifying jumps in activities. Take 30 s and 100 m distance as criterion now.</li> <li>GH-107: Remove warning by fixing a Pandas slice assignment.</li> <li>GH-108: Calories and steps are now extracted from FIT files.</li> <li> <p>GH-109: Better error message when trying to start up without any activity files.</p> </li> <li> <p>Removed <code>imagehash</code> from the dependencies.</p> </li> <li>Single day overview is now linked from each activity.</li> <li>Parsing of activity files is now parallelized over all CPU cores and faster than before.</li> <li>The coloring of the speed along the activity line doesn't remove outliers any more.</li> </ul>"},{"location":"reference/changelog/#version-020","title":"Version 0.20","text":"<ul> <li>GH-88: Fix failure to import Strava distance stream due to <code>unsupported operand type(s) for /: 'list' and 'int'</code>.</li> <li>GH-90: Take time jumps into account in activity distance computation and the various plots of the activities.</li> <li>GH-91: Import altitude information from GPX files if available.</li> <li>GH-92: Keep identity of activities based on hash of the file content, not the path. This allows to rename activities and just update their metadata, without having duplicates.</li> <li>GH-99: Skip Strava export activities that don't have a file.</li> <li>GH-98: Also accept boolean values in commute column of Strava's <code>activities.csv</code>.</li> <li>GH-100: Protect fingerprint computation from bogus values</li> <li>GH-102: Make dependency on <code>vegafusion[embed]</code> explicit in the dependencies.</li> <li>GH-103: Delete old pickle file before moving the new one onto it.</li> </ul>"},{"location":"reference/changelog/#version-019","title":"Version 0.19","text":""},{"location":"reference/changelog/#version-0191","title":"Version 0.19.1","text":"<ul> <li>Fix broken import of CSV files due to missing argument <code>opener</code>.</li> </ul>"},{"location":"reference/changelog/#version-0190","title":"Version 0.19.0","text":"<ul> <li>GH-88: Fix confusion about the internal data type for distance. Most of the time it was in meter, but the display was always in kilometer. In order to make it more clear now, the internal data now only contains the field <code>distance_km</code> and everything is represented as kilometer internally now.</li> <li>Add more tooltip information in the plot on the landing page.</li> <li>GH-87: Add <code>prefer_metadata_from_file</code> configuration option.</li> <li>GH-17: Download calories from Strava via the detailed API.</li> <li>Add option <code>--skip-strava</code> to the <code>serve</code> command in order to start the webserver without reaching out to Strava first. This might be useful if the rate limit has been exceeded.</li> <li>GH-89: Refactor some paths into a module such that there are not so many redundant definitions around.</li> <li>GH-86: Attempt to also read Strava exports that are localized to German, though untested.</li> <li>GH-36: Add a square planner.</li> </ul>"},{"location":"reference/changelog/#version-018","title":"Version 0.18","text":"<ul> <li>Fix internal server error 500 when there are not-a-number entries in the speed. GH-85</li> <li>Display activity source path in detail view.</li> <li>Ignore files which start with a period. This should also avoid Apple Quarantine files. GH-83</li> <li>Allow to have both Strava API and activity files.</li> <li>Use an existing Strava Export to load activities, retrieve only the remainder from the Strava API.</li> <li>In the calender, give the yearly total.</li> </ul>"},{"location":"reference/changelog/#version-017","title":"Version 0.17","text":""},{"location":"reference/changelog/#version-0175","title":"Version 0.17.5","text":"<ul> <li>Convert FIT sport type enum to strings. GH-84</li> </ul>"},{"location":"reference/changelog/#version-0174","title":"Version 0.17.4","text":"<ul> <li>Try to use charset-normalizer to figure out the strange encoding. GH-83</li> </ul>"},{"location":"reference/changelog/#version-0173","title":"Version 0.17.3","text":"<ul> <li>Fix error handler for GPX encoding issues. GH-83</li> </ul>"},{"location":"reference/changelog/#version-0172","title":"Version 0.17.2","text":"<ul> <li>Fix FIT import failure when the sub-sport is none. GH-84</li> </ul>"},{"location":"reference/changelog/#version-0171","title":"Version 0.17.1","text":"<ul> <li>Use locally downloaded tiles for all maps, this way we do not need to download them twice for activities and explorer/heatmap.</li> <li>Localize SimRa files to local time zone. GH-80</li> <li>Parse speed unit from FIT file. There are many devices which record in m/s and not in km/h, yielding too low speeds in the analysis. This is now fixed. GH-82</li> <li>Skip <code>.DS_Store</code> files in the activity directory. GH-81</li> <li>From FIT files we also extract the grade, temperature and GPS accuracy fields if they are present. There is no analysis for them yet, though. Also extract the workout name, sport and sub-sport fields from FIT files. GH-81</li> <li>Add more logging to diagnose Unicode issue on macOS. GH-83</li> </ul>"},{"location":"reference/changelog/#version-0170","title":"Version 0.17.0","text":"<ul> <li>Fix bug which broke the import of <code>.tcx.gz</code> files.</li> <li>Add <code>Dockerfile</code> such that one can easily use this with Docker. GH-78</li> <li>Add support for the CSV files of the SimRa Project. GH-79</li> </ul>"},{"location":"reference/changelog/#version-016","title":"Version 0.16","text":""},{"location":"reference/changelog/#version-0164","title":"Version 0.16.4","text":"<ul> <li>Fix syntax error.</li> </ul>"},{"location":"reference/changelog/#version-0163","title":"Version 0.16.3","text":"<ul> <li>Ignore Strava activities without a time series.</li> </ul>"},{"location":"reference/changelog/#version-0162","title":"Version 0.16.2","text":"<ul> <li>Make heatmap images that are downloaded look the same as the interactive one.</li> <li>Always emit the path when there is something wrong while parsing an activity file.</li> </ul>"},{"location":"reference/changelog/#version-0161","title":"Version 0.16.1","text":"<ul> <li>Fix handling of TCX files on Windows. On that platform one cannot open the same file twice, therefore my approach failed. Now I close the file properly such that this should work on Windows as well.</li> </ul>"},{"location":"reference/changelog/#version-0160","title":"Version 0.16.0","text":"<ul> <li>Add feature to render heatmap from visible area. GH-73</li> <li>Remove heatmap image generation from clusters, remove Scikit-Learn dependency.</li> <li>Add offsets for equipment. GH-71</li> <li>Fix number of tile visits in explorer view. GH-69</li> <li>Add action to convert Strava checkout to our format. GH-65</li> <li>Filter out some GPS jumps. GH-54</li> <li>Add simple search function. GH-70</li> </ul>"},{"location":"reference/changelog/#version-015","title":"Version 0.15","text":""},{"location":"reference/changelog/#version-0153","title":"Version 0.15.3","text":"<ul> <li>Create temporary file for TCX parsing in the same directory. There was a problem on Windows where the program didn't have access permissions to the temporary files directory.</li> </ul>"},{"location":"reference/changelog/#version-0152","title":"Version 0.15.2","text":"<ul> <li>Try to open GPX files in binary mode to avoid encoding issues. GH-74</li> </ul>"},{"location":"reference/changelog/#version-0151","title":"Version 0.15.1","text":"<ul> <li>Add <code>if __name__ == \"__main__\"</code> clause such that one can use <code>python -m geo_activity_playground</code> on Windows.</li> </ul>"},{"location":"reference/changelog/#version-0150","title":"Version 0.15.0","text":"<ul> <li>Export all missing tiles in the viewport, not just the neighbors.</li> <li>Automatically retry Strava API when the rate limit is exhausted. GH-67</li> <li>Give more helpful error messages when the are no activity files present.</li> </ul>"},{"location":"reference/changelog/#version-014","title":"Version 0.14","text":""},{"location":"reference/changelog/#version-0142","title":"Version 0.14.2","text":"<ul> <li>Fix broken Strava import (bug introduced in 0.14.0).</li> </ul>"},{"location":"reference/changelog/#version-0141","title":"Version 0.14.1","text":"<ul> <li>Fix hard-coded part in KML import (bug introduced in 0.14.0).</li> </ul>"},{"location":"reference/changelog/#version-0140","title":"Version 0.14.0","text":"<ul> <li>Do more calculations eagerly at startup such that the webserver is more responsive. GH-58</li> <li>Allow setting host and port via the command line. GH-61</li> <li>Re-add download of explored tiles in area. GH-63</li> <li>Unify time handling, use UTC for all internal representations. GH-52</li> <li>Add some sort of KML support that at least works for KML exported by Viking. GH-62</li> </ul>"},{"location":"reference/changelog/#version-013","title":"Version 0.13","text":"<ul> <li>Revamp heatmap, use interpolated lines to provide a good experience even at high zoom levels.</li> <li>This also fixes the gaps that were present before. GH-34</li> <li>Add cache migration functionality.</li> <li>Make sure that cache directory is created beforehand. GH-55</li> <li>Split tracks into segments based on gaps of 30 seconds in the time data. That helps with interpolation across long distances when one has paused the recording. GH-47</li> <li>Fix introduced bug. GH-56</li> <li>Add cache to heatmap such that it doesn't need to render all activities and only add new activities as needed.</li> <li>Add a footer. GH-49</li> <li>Only export missing tiles in the active viewport. GH-53</li> <li>Add missing dependency to SciKit Learn again; I was too eager to remove that. GH-59</li> </ul>"},{"location":"reference/changelog/#version-012","title":"Version 0.12","text":"<ul> <li>Change coloring of clusters, have a color per cluster. Also mark the square just as an overlay.</li> <li>Fix bug with explorer tile page when the maximum cluster or square is just 1. GH-51</li> <li>Speed up the computation of the latest tiles.</li> </ul>"},{"location":"reference/changelog/#version-011","title":"Version 0.11","text":"<ul> <li>Add last activity in tile to the tooltip. GH-35</li> <li>Add explorer coloring mode by last activity. GH-45</li> <li>Actually implement <code>Activity/{Kind}/{Equipment}/{Name}.{Format}</code> directory structure.</li> <li>Document configuration file.</li> <li>Interpolate tracks to find more explorer tiles. GH-27</li> <li>Fix bug that occurs when activities have no distance information.</li> <li>Show time evolution of the number of explorer tiles, the largest cluster and the square size. GH-33</li> <li>Center map view on biggest explorer cluster.</li> <li>Show speed distribution. GH-42</li> </ul>"},{"location":"reference/changelog/#version-010","title":"Version 0.10","text":"<ul> <li>Use a grayscale map for the explorer tile maps. GH-38</li> <li>Explicitly write \u201c0 km\u201d in calendar cells where there are no activities. GH-39, GH-40</li> </ul>"},{"location":"reference/changelog/#version-09","title":"Version 0.9","text":"<ul> <li>Certain exceptions are not skipped when parsing files. This way one can gather all errors at the end. GH-29</li> <li>Support TCX files. GH-8</li> <li>Fix equipment view when using the directory source. GH-25</li> <li>Fix links from the explorer tiles to the first activity that explored them. GH-30</li> <li>Fix how the API response from Strava is handled during the initial token exchange. GH-37</li> </ul>"},{"location":"reference/changelog/#version-08","title":"Version 0.8","text":""},{"location":"reference/changelog/#version-083","title":"Version 0.8.3","text":"<ul> <li>Only compute the explorer tile cluster size if there are cluster tiles. Otherwise the DBSCAN algorithm doesn't work anyway. GH-24</li> <li>Remove allocation of huge array. GH-23</li> </ul>"},{"location":"reference/changelog/#version-082","title":"Version 0.8.2","text":"<ul> <li>Some FIT files apparently have entries with explicit latitude/longitude values, but those are null. I've added a check which skips those points.</li> </ul>"},{"location":"reference/changelog/#version-081","title":"Version 0.8.1","text":"<ul> <li>Fix reading of FIT files from Wahoo hardware by reading them in binary mode. GH-20.</li> <li>Fix divide-by-zero error in speed calculation. GH-21</li> </ul>"},{"location":"reference/changelog/#version-080","title":"Version 0.8.0","text":"<ul> <li>Make heart rate zone computation a bit more flexibly by offering a lower bound for the resting heart rate.</li> <li>Open explorer map centered around median tile.</li> <li>Compute explorer cluster and square size, print that. GH-2</li> <li>Make it compatible with Python versions from 3.9 to 3.11 such that more people can use it. GH-22</li> </ul>"},{"location":"reference/changelog/#version-07","title":"Version 0.7","text":"<ul> <li>Add Squadratinhos, which are explorer tiles at zoom 17 instead of zoom 14.</li> <li>Reduce memory footprint for explorer tile computation.</li> </ul>"},{"location":"reference/changelog/#version-06","title":"Version 0.6","text":"<ul> <li>Interactive map for each activity.</li> <li>Color explorer tiles in red, green and blue. GH-2</li> <li>Directly serve GeoJSON and Vega JSON embedded in the document.</li> <li>Automatically detect which source is to be used. GH-16</li> <li>Fix the name of the script to be <code>geo-activity-playground</code> and not just <code>geo-playground</code>. GH-11</li> <li>Add mini maps to the landing page. GH-9</li> <li>Add fullscreen button to the maps. GH-4</li> <li>Add favicon. GH-19</li> <li>Added some more clever caching to the explorer tiles such that loading the page with explorer tiles comes up in just a few seconds.</li> <li>Add a triplet of time series plots (distance, altitude, heart rate) for each activity.</li> <li>Show plot for heart rate zones per activity. GH-12</li> <li>Handle activities without any location points. GH-10</li> <li>Resolve Strava Gear name. GH-18</li> <li>Add page for equipment. GH-3</li> <li>Add a pop-up with some metadata about the first visit to the explorer tiles. GH-14</li> <li>Integrate missing explorer tiles into the web interface. GH-7.</li> <li>Color activity line with speed. GH-13</li> <li>Add interactive heatmap.</li> <li>Add margin to generated heatmaps. GH-1</li> </ul>"},{"location":"reference/changelog/#version-05","title":"Version 0.5","text":"<ul> <li>Add some plots for the Eddington number. GH-3</li> </ul>"},{"location":"reference/changelog/#version-04","title":"Version 0.4","text":"<ul> <li>Add some more plots.</li> </ul>"},{"location":"reference/changelog/#version-03","title":"Version 0.3","text":"<ul> <li>Start to build web interface with Flask.</li> <li>Remove tqdm progress bars and use colorful logging instead.</li> <li>Add interactive explorer tile map.</li> </ul>"},{"location":"reference/changelog/#version-02","title":"Version 0.2","text":"<ul> <li>Unity command line entrypoint.</li> <li>Crop heatmaps to fit.</li> <li>Export missing tiles as GeoJSON.</li> <li>Add Strava API.</li> <li>Add directory source.</li> </ul>"},{"location":"reference/changelog/#version-01","title":"Version 0.1","text":""},{"location":"reference/changelog/#version-013_1","title":"Version 0.1.3","text":"<ul> <li>Generate some heatmap images.</li> <li>Generate an explorer tile video.</li> </ul>"}]}
\ No newline at end of file
diff --git a/sitemap.xml b/sitemap.xml
index 9702acd..e414af7 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,98 +2,98 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/acknowledgments/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/features/activity-view/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/features/calendar/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/features/eddington/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/features/equipment/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/features/explorer-tiles/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/features/heatmaps/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/features/kind-rename/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/features/overview/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/features/share-picture/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/features/upload/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/getting-started/advanced-metadata-extraction/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/getting-started/docker-compose-tailscale/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/getting-started/docker-compose/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/getting-started/docker/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/getting-started/installing-git-on-linux/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/getting-started/installing-stable-on-linux/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/getting-started/installing-stable-on-windows/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/getting-started/moving-from-strava/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/getting-started/starting-the-webserver/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/getting-started/using-activity-files/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/getting-started/using-strava-api/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
     <url>
          <loc>https://martin-ueding.github.io/geo-activity-playground/reference/changelog/</loc>
-         <lastmod>2025-01-03</lastmod>
+         <lastmod>2025-01-04</lastmod>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index f2205f4238b22fe21937c471a3d88abdb098d703..1e5cb8fa488eae32bf0f1add4087baa4620933d1 100644
GIT binary patch
delta 30
mcmX@fe3F@6zMF%Cp{imcyBy=fjcT(QIk-OF-gbtcfdK%G2MLA%

delta 30
mcmX@fe3F@6zMF%iL8E*kyBwqFMzz_D9I;&PpU&_zFaQ99UkEz@