mwio/jogging-dashboard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated the README.md to the latest version.

Browse Source
This commit is contained in:
Marcel Weschke
2026-05-05 15:00:59 +02:00
parent b4c6d409a7
commit 2eb0513d40
1 changed files with 86 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
README.md
View File

@@ -8,7 +8,7 @@ Interactive Python Dash app to visualize, analyze, and explore your jogging or r
SVG-Export: SVG-Export:
<p align="left"> <p align="left">
<img src="2025-09-15_HH_Run_10.90Km_overlay.png" alt="Description" width="600"> <img src="2025-09-15_HH_Run_10.90Km_overlay.png" alt="Description" width="400">
</p> </p>
This SVG can then be overlaid on another image (Strava‑inspired). This SVG can then be overlaid on another image (Strava‑inspired).
@@ -16,15 +16,37 @@ This SVG can then be overlaid on another image (Strava‑inspired).
## Features ## Features
- **Select file** choose a data file to analyse your run ### 📊 Info & Navigation
- **export SVG** creates a transparent SVG image of your Course and the Info Banner statistics (Strava‑inspired) - **Select file** — choose any `.gpx` or `.fit` file from the dropdown to analyze your run
- **Info Banner** with total distance, duration, and average pace - **Export SVG** — creates a transparent SVG overlay of your route and stats (Strava‑inspired)
- **Interactive Map View** with route trace and start/stop markers - **Info Banner** — total distance, duration, average pace, elevation gain, and estimated calories burned
- **Elevation Profile** with relative height and gradient fill
- **Speed Over Time** plot with smoothing and average line ### 🗺️ Map & Standard Plots
- **Heart Rate Over Time** plot with smoothing and average line (if .fit file) - **Interactive Map View** — route trace with start/stop markers and hover interaction linked to the elevation profile
- **Deviation from Mean Speed** to see pacing consistency - **Elevation Profile** — relative height over time, color-coded per segment: red = climbing, grey = flat, green = descending
- **Pace Bar Chart** showing per-kilometer pace breakdown - **Speed Over Time** — smoothed speed curve with average reference line
- **Heart Rate Over Time** — smoothed HR curve with zone overlays and percentage breakdown (`.fit` files only)
- **Deviation from Mean Speed** — pacing consistency over the run
- **Pace Bar Chart** — per-kilometer pace breakdown with average reference line
### 🔥 Pixel Maps (Sam-Style)
Three additional pixel-accurate route maps rendered below the main map, inspired by [Sam's approach](https://youtu.be/PA8d4u5T4BM?t=240) of drawing GPS routes pixel by pixel:
- **Heatmap** — draws the route pixelwise and counts how often each pixel was crossed. Segments you run frequently glow brighter (dark → orange → white). Supports two modes toggled via a switch below the plot:
- *Single run* — shows only the currently selected run, but the color intensity is still derived from the full regional count grid so you can see how often you have been at each spot across all your runs
- *All runs (Region)* — overlays all runs from the same city/region (detected automatically from the filename, e.g. `2025-07-30_FRA_Run_6.68Km.fit` → region `FRA`). This is the default view.
- **Elevation Map** — the route is color-coded segment by segment based on the gradient between consecutive GPS points: red = climbing, grey = flat, green = descending. Intensity scales with steepness. GPS noise is removed via smoothing before the gradient is calculated, giving accurate up/down statistics in the title.
- **Pace Map** — each segment is colored by your running pace at that location: blue = fast, red = slow. A horizontal colorbar below the plot shows the pace scale. Outliers (stops, GPS jumps) are filtered automatically.
#### City/Region detection from filename
The heatmap automatically groups runs by city code extracted from the filename at position `[1]` after splitting by `_`:
```
2025-07-30_FRA_Run_6.68Km.fit → region: FRA (Frankfurt)
2025-09-10_HH_Run_10.27Km.fit → region: HH (Hamburg)
```
Use any consistent 2–6 letter code in your filenames to group runs by region.
--- ---
@@ -32,7 +54,7 @@ This SVG can then be overlaid on another image (Strava‑inspired).
``` ```
jogging_dashboard_browser_app.py # Main Dash application (Web-Version) jogging_dashboard_browser_app.py # Main Dash application (Web-Version)
jogging_dashboard_gui_app.py # Main Dash application (loading Web-Version in a Gui) jogging_dashboard_gui_app.py # Main Dash application (loading Web-Version in a GUI)
gpx_files/ # Folder for storing GPX files gpx_files/ # Folder for storing GPX files
fit_files/ # Folder for storing FIT files fit_files/ # Folder for storing FIT files
requirements.txt # Required Python packages requirements.txt # Required Python packages
@@ -52,7 +74,7 @@ cd jogging-dashboard
### 2. Install dependencies ### 2. Install dependencies
It is recommend using a virtual environment: It is recommended to use a virtual environment:
```bash ```bash
python -m venv venv python -m venv venv
@@ -60,25 +82,29 @@ source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt pip install -r requirements.txt
``` ```
**Content of the requirements.txt file**: **Content of the `requirements.txt` file:**
[Dash & Web Components] ```
- dash # Dash & Web Components
- dash-bootstrap-components dash
- plotly dash-bootstrap-components
- pandas plotly
- numpy pandas
- scipy numpy
- gpxpy scipy
- fitparse gpxpy
fitparse
matplotlib
[GUI Version (PyQt6)] # GUI Version (PyQt6)
- PyQt6 PyQt6
- PyQt6-WebEngine PyQt6-WebEngine
[Additional Dependencies (usually automatically installed)] # Additional (usually installed automatically)
- requests requests
```
> **Note:** `matplotlib` is required for the Pixel Maps feature and must be added to your `requirements.txt` if not already present.
### 3. Run the app ### 3. Run the app
@@ -89,7 +115,7 @@ python jogging_dashboard_browser_app.py
Then open your browser and go to: Then open your browser and go to:
[http://127.0.0.1:8051](http://127.0.0.1:8051) [http://127.0.0.1:8051](http://127.0.0.1:8051)
Or as Gui-Version Or as GUI-Version:
```bash ```bash
python jogging_dashboard_gui_app.py python jogging_dashboard_gui_app.py
@@ -97,38 +123,55 @@ python jogging_dashboard_gui_app.py
--- ---
## Uploading Your GPX File ## Uploading Your Activity File
1. Export your activity (e.g., from Strava, Garmin, etc.) as a `.gpx` or `.fit` file 1. Export your activity (e.g., from Strava, Garmin, etc.) as a `.gpx` or `.fit` file
2. Place the file into the `gpx_files/` or `fit_files/` directory 2. Use the recommended filename format for region grouping in the Heatmap:
3. Select it via the dropdown in the dashboard ```
YYYY-MM-DD_CITYCODE_Run_DISTANCEKm.fit
e.g. 2025-07-30_FRA_Run_6.68Km.fit
```
3. Place the file into the `gpx_files/` or `fit_files/` directory
4. Select it via the dropdown in the dashboard
--- ---
## Tech Stack ## Tech Stack
- **Dash** (by Plotly) for building the UI and graphs - **Dash** (by Plotly) — UI framework and interactive graphs
- **Pandas** for data wrangling - **Pandas** — data wrangling and processing
- **Plotly Graph Objects & Express** for advanced visuals - **Plotly Graph Objects & Express** — advanced interactive visuals
- **Scipy** for smoothing the data lines - **Scipy** — smoothing the data lines
- **GPXPy** for parsing `.gpx` files - **Matplotlib** — pixel-accurate route rendering for the three Pixel Maps
- **Numpy** for vectorized math and smoothing - **GPXPy** — parsing `.gpx` files
- **FitParse** for parsing `.fit` files - **NumPy** — vectorized math and smoothing
- **FitParse** — parsing `.fit` files
--- ---
## Example GPX File ## Example File
You can test the dashboard by either placing any valid `.gpx` file in the `gpx_files/` or any valid `.fit` file in the `fit_files/` directory. You can test the dashboard by placing any valid `.gpx` or `.fit` file in the respective directory.
Make sure it contains track points with elevation and time data. Make sure it contains track points with time, GPS coordinates, and ideally elevation data.
For full Pixel Map functionality (especially the Heatmap region view), use the filename convention:
```
YYYY-MM-DD_CITYCODE_Run_DISTANCEKm.fit
```
--- ---
## To Do / Ideas ## To Do / Ideas
- [X] Plotting heart rate data - **if** FIT file choosen. - [X] Plotting heart rate data — if `.fit` file chosen
- [X] Pixel Heatmap — frequency map across multiple runs per region
- [X] Pixel Elevation Map — per-segment gradient coloring on the route
- [X] Pixel Pace Map — per-segment pace coloring on the route
- [X] Elevation gain calculation calibrated against Strava
- [X] Calories burned estimation via HR-based Karvonen formula
- [X] GPX file support in addition to FIT
- [ ] Export as PDF report - [ ] Export as PDF report
- [ ] Multi-run comparison - [ ] Multi-run comparison overlay
--- ---