gradient-ascent

CLI tools for discovering long, steep trail routes in the French Alps using OpenStreetMap trails and Copernicus DEM data.
The route-finding algorithm is very largely LLM-written and only "sort-of works". This repo exists both because I enjoy hiking steep trails and because I wanted to test AI coding tools on a non-trivial problem.

Getting started

• Python 3.13 is expected. Create a virtualenv and install dependencies:

  python -m venv .venv
  source .venv/bin/activate
  pip install --upgrade pip
  pip install -r requirements.txt

• Planner paths can be overridden via environment variables:
  • GA_DATA_DIR (default data/)
  • GA_DEM_DIR (default data/dem/)
  • GA_CACHE_DIR (default data/cache/)
  • GA_EXPORT_DIR (default data/exports/)
  • GA_PROVENANCE_DIR (default data/provenance/)
• Copernicus credentials for DEM downloads (required for dem fetch and auto-downloads):
  • CDSE_USERNAME, CDSE_PASSWORD
  • CDSE_S3_ACCESS_KEY, CDSE_S3_SECRET_KEY
  • Optional: CDSE_S3_ENDPOINT, CDSE_S3_REGION, CDSE_TOTP
• Overpass controls: set GA_OVERPASS_RATE_LIMIT=1 or 0 to toggle osmnx rate limiting when using the default endpoint.

CLI essentials

• Find steep routes (writes a manifest to data/exports/runs/):

  python -m gradient_ascent.cli planner "5.9,45.8,7.2,46.6" \
    --min-gain 1200 --max-distance 18000 --results 10 --verbose

• Download Copernicus DEM tiles for a bounding box:

  python -m gradient_ascent.cli dem fetch --bbox "5.5,44.0,7.5,46.5" --resolution 30

• Render a saved manifest to an HTML map (defaults to <manifest>.html):

  python -m gradient_ascent.cli render-manifest data/exports/runs/<run>.json

• Export GPX from a manifest:

  python -m gradient_ascent.cli export-gpx data/exports/runs/<run>.json --include-elevation

Logging

• Logs are sent to stderr and to timestamped files such as logs/gradient_ascent_20250110-143000_12345.log.
• Increase verbosity with --verbose or GA_LOG_LEVEL=DEBUG.
• Override destinations with GA_LOG_FILE (full path) or GA_LOG_DIR (directory for auto-generated filenames).
• When --overpass-endpoint is set, osmnx rate limiting is disabled automatically; otherwise control it with GA_OVERPASS_RATE_LIMIT=1/0.

Documentation

• See docs/index.md for the doc map, current specification, and active plans.