diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 48 |
1 files changed, 9 insertions, 39 deletions
@@ -1,6 +1,6 @@ # biking_home — cycling ride analysis -A Go toolkit for analyzing cycling rides from GPX exports: parse rides, detect climbs, score their difficulty, match the same climb across rides, and download French mountain passes into SQLite. +A Go toolkit for analyzing cycling rides from GPX exports: parse rides, detect climbs, score their difficulty, match the same climb across rides, and load French mountain passes from OpenStreetMap into SQLite. ## Features @@ -8,8 +8,8 @@ A Go toolkit for analyzing cycling rides from GPX exports: parse rides, detect c - **Climb detection** — automatically finds climbs within a ride, each scored and categorized (Cat 4 … HC) - **Difficulty score (Cotacol)** — scores any ride or climb by splitting it into 100 m segments and summing `0.1 km × slope²` per segment. This fixed step is a deliberate compromise: smaller steps increase sensitivity to elevation noise, while unconstrained variable steps maximize noise rather than meaningful difficulty. - **Similar-climb matching** — finds the same climb across rides by matching start/end coordinates, so times can be compared -- **Mountain pass download** — imports French mountain passes from centcols.org into a SQLite database -- **Pass crossing detection** — enriches passes with OSM coordinates, flags which passes a ride crosses, and names each climb after the pass it tops (e.g. "Col de Castellaras") +- **Mountain pass extraction** — extracts French mountain passes from an OpenStreetMap PBF export (nodes tagged `mountain_pass=yes` / `natural=mountain_pass`) into a SQLite database +- **Pass crossing detection** — flags which passes a ride crosses and names each climb after the pass it tops (e.g. "Col de Castellaras") - **Interactive ride profiles** — explores elevation, climbs, and mountain-pass crossings in the web ride detail view - **Official climb cards** — separates matched climbs from pending matches and expands each matched climb with its own elevation profile - **Web ride library** — starts a local web server by default, imports Strava rides over a date range, stores metadata in SQLite, and keeps their GPX files on disk @@ -33,40 +33,16 @@ mise run build ```bash # Start the web server on http://localhost:8080 mise run dev-watch - -# Recompute and persist all ride computed values -./biking_home -backfill - -# Run data benchmarks comparing computed values against stored references -./biking_home -backtest - -# Download French mountain passes into biking_home.db (SQLite) -./biking_home -download - -# Resume an interrupted download, reusing departments already cached on disk -./biking_home -download -resume - -# Import cached department CSVs (debug_department_06.csv, 13.csv) into the DB -./biking_home -import-cached - -# Extract mountain passes from a France OSM PBF into the DB -./biking_home -extract-osm /path/to/france-latest.osm.pbf - -# Backfill OSM coordinates onto passes (needs -extract-osm run first) -./biking_home -enrich - ``` ## Options / Configuration | Flag | Description | Default | | --- | --- | --- | -| `-download` | Download mountain passes into the database | `false` | -| `-resume` | Skip departments already cached on disk | `false` | -| `-import-cached` | Import cached department CSVs into the database | `false` | +| `-fetch-osm` | Download the France OSM PBF (resumable) | `false` | | `-extract-osm` | Extract mountain passes from a France OSM PBF | `""` | -| `-enrich` | Backfill OSM coordinates onto passes | `false` | | `-backfill` | Recompute and persist all ride computed values | `false` | +| `-backtest` | Benchmark computed vs stored ride values | `false` | Configuration is stored in `config.yaml`. Start from `config.example.yaml` and set the Strava credentials before launching the server. @@ -86,14 +62,12 @@ Standard apps are rate-limited to 100 calls per 15 minutes and 1,000 per day. - Go 1.23; SQLite via `mattn/go-sqlite3` - `ride` — GPX parsing, climb detection, difficulty scores (KOM + Cotacol), similarity index -- `mountain_pass` — centcols.org department CSV download into SQLite, with disk caching and retries -- `osmpass` — OSM PBF extraction (`mountain_pass=yes` nodes) and pass coordinate enrichment +- `mountain_pass` — OSM PBF extraction (`mountain_pass=yes` / `natural=mountain_pass` nodes), pass storage and querying, and crossings/climb matching - `strava` — OAuth2 client returning activity metadata and GPX data - `rides` — SQLite persistence for imported ride metadata and versioned computed values - `config` — typed YAML configuration and atomic persistence - `web` — HTTP server, OAuth callback, sync orchestration, and templ pages -- `cli` — legacy mountain-pass and OSM command handlers -- **Notable choices** — the difficulty score follows the Cotacol method: the ride is split into fixed 100 m segments and each scores `distance_km × slope²`, so steep sections weigh exponentially more than long flat ones +- `cli` — command handlers for data import, backfill, and benchmarking ```mermaid flowchart TB @@ -102,18 +76,16 @@ flowchart TB main["main (bootstrap: main.go)"] ride["ride (GPX parsing, climbs, Cotacol)"] - mpass["mountain_pass (centcols, crossings)"] - osmpass["osmpass (OSM PBF, enrichment)"] + mpass["mountain_pass (OSM PBF, crossings)"] strava["strava (OAuth, List, Get)"] rides["rides (SQLite persistence)"] config["config (YAML)"] web["web (HTTP + templ)"] - cli["cli (legacy commands)"] + cli["cli (import, backfill, benchmark)"] main --> cli cli --> ride cli --> mpass - cli --> osmpass cli --> web mpass --> ride web --> strava @@ -151,14 +123,12 @@ TypeScript checks can also be run directly with `npm run check`, covering format - Record ride times on official climbs - Destination via Start - Planning rides -- Mountain pass from OSM - performance/profile tracking - progress bar cli ## Resources - [Climbfinder: difficulty points](https://climbfinder.com/en/difficulty-points) — the Cotacol formula behind the difficulty score -- [centcols.org](https://www.centcols.org) — French mountain pass reference used for the SQLite data - [Pogacar 21 July 2022](https://www.strava.com/activities/7505784085) — example ride used for climb detection - [gpxgo](https://github.com/tkrajina/gpxgo) — GPX parsing library - [geodist](https://github.com/jftuga/geodist) — haversine distance used for climb matching |