GPX / KML Route Visualizer

Overview

Convert GPS track files (KML/GPX) into professional route visualization outputs:

• Static JPG: High-resolution image with route map + elevation profile + statistics panel
• Interactive HTML: Browser-based Leaflet map with zoom, layer switching, and embedded elevation chart

Workflow

Step 1: Parse Track File

Run the parsing script to extract coordinates and compute statistics:

python scripts/parse_track.py <input.kml|input.gpx> -o track_data.json

This produces a JSON file containing:

• Parsed track points (lat, lon, ele, cumulative dist)
• Route statistics (total distance, elevation gain/loss, max/min/average elevation)

Step 2: Generate Visualization

Choose output format based on user request:

Option A: Static JPG Image

Generate a printable/static route map image:

python scripts/plot_static.py track_data.json -o route_map.jpg --dpi 150

Output layout:

• Top panel: Route trajectory with elevation-based color gradient, start/end markers, elevation colorbar
• Bottom panel: Distance vs. elevation profile with gain/loss annotations
• Footer: Key statistics text strip

Option B: Interactive HTML Map

Generate a browser-based interactive map:

python scripts/plot_interactive.py track_data.json -o route_map.html

Features:

• Leaflet map centered on route with OSM, Satellite, and Terrain tile layers
• Route colored by elevation (viridis gradient)
• Clickable start/end markers with coordinates and elevation
• Auto-fit bounds to show entire route
• Embedded elevation profile image below the map
• Statistics header panel

Combined One-Liner Workflow

For quick generation, chain the scripts:

# Static JPG
python scripts/parse_track.py input.gpx -o track_data.json && python scripts/plot_static.py track_data.json -o route_map.jpg

# Interactive HTML
python scripts/parse_track.py input.gpx -o track_data.json && python scripts/plot_interactive.py track_data.json -o route_map.html

Dependencies

Required Python packages:

pip install matplotlib numpy folium Pillow

• matplotlib: Static plotting and image generation
• numpy: Numerical operations for statistics
• folium: Interactive Leaflet HTML map generation
• Pillow: Image handling (usually installed with matplotlib)

All scripts use only the Python standard library plus the above packages.

Script Reference

File Format Support

• KML: Parses <coordinates> elements inside <LineString> (handles both KML 2.1 and 2.2 namespaces)
• GPX: Parses <trkpt> elements with lat/lon attributes and <ele> child elements (GPX 1.1)

For detailed format specifications, see references/formats.md.

Notes

• Static JPG DPI can be increased (--dpi 300) for print-quality output
• Interactive HTML is fully self-contained (no external dependencies after generation) except for map tile CDN requests
• The parser handles both namespaced and non-namespaced XML automatically
• Large track files (>100k points) may take several seconds to process