# 🏃‍♂️ 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.
