docs: add technical and high-level documentation

2026-11-09 15:05:02 +01:00
parent fb49e1b553
commit 4c3bee89ed
2 changed files with 140 additions and 0 deletions
@@ -0,0 +1,53 @@
+# connect2gpx — Présentation
+
+## En une phrase
+
+`connect2gpx` transforme un lien de **trail Garmin Connect** en fichier **GPX**
+que l'on peut ouvrir dans n'importe quelle application de randonnée ou de
+navigation (Garmin, Komoot, Strava, OsmAnd, etc.).
+
+## Le problème
+
+Garmin Connect propose une section « Trails » avec des parcours curatés affichés
+sur une carte. Ces parcours sont consultables en ligne, mais il n'est pas
+toujours simple d'en récupérer la trace GPS au format GPX pour la charger sur
+un appareil ou la partager.
+
+## Ce que fait l'outil
+
+1. **Vous lui donnez l'URL** d'une page Garmin Trails (par exemple une boucle
+   dans le Hainaut).
+2. **Il ouvre automatiquement un navigateur invisible** (Chromium) pour
+   contourner la protection anti-robots de Garmin.
+3. **Il récupère la trace complète** du parcours, point par point, avec
+   l'altitude.
+4. **Il écrit un fichier `.gpx`** standard, prêt à être utilisé.
+
+## Résultat
+
+Un fichier GPX contenant :
+- le nom et la description du trail ;
+- la trace complète (latitude, longitude, altitude) ;
+- typiquement plusieurs centaines à milliers de points.
+
+Pour l'exemple analysé (« Boucle de Poteaupré et Étang de Virelles ») :
+854 points, ~20,7 km, dénivelé positif ~251 m.
+
+## Utilisation
+
+```bash
+connect2gpx "https://connect.garmin.com/app/trails/..." -o sortie.gpx
+```
+
+## Prérequis
+
+- Python 3.13 ou supérieur
+- Chromium ou Google Chrome installé sur la machine
+
+## Limites
+
+- Fonctionne uniquement avec les **trails publics** de Garmin Connect (pas
+  avec vos activités personnelles, qui nécessitent une authentification).
+- Dépend de la structure interne du site Garmin : si Garmin modifie son site,
+  l'outil peut nécessiter une mise à jour.
+- Un parcours prend environ 10 à 20 secondes à récupérer.