207 lines
7.0 KiB
Markdown
207 lines
7.0 KiB
Markdown
# 🏃♂️ Jogging Dashboard
|
||
|
||
Interactive Python Dash app to visualize, analyze, and explore your jogging or running sessions recorded as GPX/FIT files.
|
||
|
||
<p align="left">
|
||
<img src="DashboardApp_WebVersion.png" alt="Description" width="800">
|
||
</p>
|
||
|
||
SVG-Export:
|
||
<p align="left">
|
||
<img src="2025-09-15_HH_Run_10.90Km_overlay.png" alt="Description" width="400">
|
||
</p>
|
||
This SVG can then be overlaid on another image (Strava‑inspired).
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
### Info & Navigation
|
||
- **Select file** — choose any `.gpx` or `.fit` file from the dropdown to analyze your run
|
||
- **Export SVG** — creates a transparent SVG overlay of your route and stats (Strava‑inspired)
|
||
- **Info Banner** — total distance, duration, average pace, elevation gain, and estimated calories burned
|
||
|
||
### Map & Standard Plots
|
||
- **Interactive Map View** — route trace with start/stop markers and hover interaction linked to the elevation profile
|
||
- **Elevation Profile** — relative height over time, color-coded per segment: red = climbing, grey = flat, green = descending
|
||
- **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
|
||
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). Toggle below the plot:
|
||
- *Single run* — shows only the selected run, color intensity derived from the full regional count grid
|
||
- *All runs (Region)* — overlays all runs from the same city/region (default). Region is detected
|
||
automatically from the filename, e.g. `2025-07-30_FRA_Run_6.68Km.fit` → region `FRA`
|
||
- **Elevation Map** — route color-coded per segment by gradient: red = climbing, grey = flat,
|
||
green = descending. GPS noise removed via smoothing before gradient calculation.
|
||
Horizontal colorbar: green (max descent) → grey (flat) → red (max climb)
|
||
- **Pace Map** — each segment colored by running pace: blue = fast, red = slow.
|
||
Outliers (stops, GPS jumps) filtered automatically.
|
||
Horizontal colorbar: red (slow) → blue (fast)
|
||
- **Heart Rate Map** — each segment colored by heart rate at that location:
|
||
dark red = low BPM (easy) → white = max BPM (full effort).
|
||
Horizontal colorbar: dark red (min BPM) → white (max BPM).
|
||
Falls back gracefully to a grey route with info text for GPX files without HR data.
|
||
|
||
#### 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.
|
||
|
||
#### Responsive layout
|
||
The four Pixel Maps are arranged in a 2×2 grid on wide screens (desktop/tablet).
|
||
On screens narrower than 768 px (smartphones) the grid collapses to a single column
|
||
so each plot uses the full screen width and remains readable.
|
||
Scroll zoom is enabled on all four plots (`scrollZoom: True`) — use the mouse wheel
|
||
on desktop or two-finger drag on mobile to pan after zooming in.
|
||
|
||
---
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
jogging_dashboard_browser_app.py # Main Dash application (Web-Version)
|
||
jogging_dashboard_gui_app.py # Main Dash application (loading Web-Version in a GUI)
|
||
gpx_files/ # Folder for storing GPX files
|
||
fit_files/ # Folder for storing FIT files
|
||
requirements.txt # Required Python packages
|
||
README.md # Project description file
|
||
```
|
||
|
||
---
|
||
|
||
## Getting Started
|
||
|
||
### 1. Clone the repository
|
||
|
||
```bash
|
||
git clone https://github.com/yourusername/jogging-dashboard.git
|
||
cd jogging-dashboard
|
||
```
|
||
|
||
### 2. Install dependencies
|
||
|
||
It is recommended to use a virtual environment:
|
||
|
||
```bash
|
||
python -m venv venv
|
||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
**Content of the `requirements.txt` file:**
|
||
|
||
```
|
||
# Dash & Web Components
|
||
dash
|
||
dash-bootstrap-components
|
||
plotly
|
||
pandas
|
||
numpy
|
||
scipy
|
||
gpxpy
|
||
fitparse
|
||
matplotlib
|
||
|
||
# GUI Version (PyQt6)
|
||
PyQt6
|
||
PyQt6-WebEngine
|
||
|
||
# Additional (usually installed automatically)
|
||
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
|
||
|
||
```bash
|
||
python jogging_dashboard_browser_app.py
|
||
```
|
||
|
||
Then open your browser and go to:
|
||
[http://127.0.0.1:8051](http://127.0.0.1:8051)
|
||
|
||
Or as GUI-Version:
|
||
|
||
```bash
|
||
python jogging_dashboard_gui_app.py
|
||
```
|
||
|
||
---
|
||
|
||
## Uploading Your Activity File
|
||
|
||
1. Export your activity (e.g., from Strava, Garmin, etc.) as a `.gpx` or `.fit` file
|
||
2. Use the recommended filename format for region grouping in the Heatmap:
|
||
```
|
||
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
|
||
|
||
- **Dash** (by Plotly) — UI framework and interactive graphs
|
||
- **Pandas** — data wrangling and processing
|
||
- **Plotly Graph Objects & Express** — advanced interactive visuals
|
||
- **Scipy** — smoothing the data lines
|
||
- **Matplotlib** — pixel-accurate route rendering for the three Pixel Maps
|
||
- **GPXPy** — parsing `.gpx` files
|
||
- **NumPy** — vectorized math and smoothing
|
||
- **FitParse** — parsing `.fit` files
|
||
|
||
---
|
||
|
||
## Example File
|
||
|
||
You can test the dashboard by placing any valid `.gpx` or `.fit` file in the respective directory.
|
||
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
|
||
|
||
- [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] Pixel Heart Rate Map — per-segment BPM coloring on the route
|
||
- [X] Elevation gain calculation calibrated against Strava
|
||
- [X] GPX file support in addition to FIT
|
||
- [X] Responsive 2×2 grid layout for Pixel Maps (collapses to single column on mobile)
|
||
- [ ] Export as PDF report
|
||
- [ ] Multi-run comparison overlay
|
||
- [ ] Pinch-to-zoom on Pixel Maps for mobile devices
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
This project is open source under the [MIT License](LICENSE).
|
||
|
||
---
|
||
|
||
## Feedback / Contributions
|
||
|
||
Feel free to open issues or pull requests!
|
||
If you enjoy this project, a ⭐️ star is always appreciated.
|