lympha

Lympha — Roman goddess of fresh water and springs.

Find drinking water fountains along a GPX cycling route and generate Garmin-compatible POI files. The search radius is adaptive: narrow in zones where fountains are plentiful, wider where they are scarce.

How it works

1. Reads a GPX track file
2. Queries OpenStreetMap Overpass API for amenity=drinking_water nodes near the route
3. Filters candidates using a density-adaptive radius (100–500 m by default)
4. Writes two output files ready to load on a Garmin Edge 530

Waypoints are named after Toy Story characters: woody_1, buzz_2, jessie_3 …

Installation

Requires Python ≥ 3.11 and uv.

git clone git@github.com:andrearota/lympha.git
cd lympha
uv sync

Usage

uv run main.py route.gpx

23:01:04  [1/5] Loading track: route.gpx
23:01:04        32,847 track points loaded (0.41s)
23:01:04  [2/5] Track split into 9 chunks of ~30 km
23:01:04  [3/5] Overpass API — 9 requests (timeout 60s each) ...
23:01:04        Chunk 1/9 ...
...
23:01:44        187 unique fountains in bbox (40.2s total)
23:01:44  [4/5] Adaptive spatial filter (min 100 m / max 500 m) ...
23:01:44        112 kept, 75 discarded by density (0.012s)
23:01:44  [5/5] Writing output to ./output/ ...
23:01:44        Unified GPX    → output/route_with_fountains.gpx
23:01:44        POI GPX        → output/route_poi.gpx

Options

Flag	Default	Description
--radius-max	500 m	Search radius in sparse zones
--radius-min	100 m	Search radius in dense zones
--density-window	5 km	Sliding window for local density computation
--chunk-km	30 km	Route chunk size per Overpass request
--timeout	60 s	Overpass query timeout per chunk
--output-dir	./output	Output directory
-v / --verbose	—	Debug logging

Output files

File	Use
<stem>_with_fountains.gpx	Copy to Garmin/NewFiles/ — course with fountain waypoints
<stem>_poi.gpx	Import with Garmin POI Loader → .gpi persistent POI layer

Data

Fountain data © OpenStreetMap contributors, ODbL.

License

MIT