gpx-to-map

Convert a folder of GPX tracks into an interactive HTML map (lonboard / deck.gl) or a static PNG image (matplotlib + contextily) with a single command.

Installation

pip install gpx-to-map

Usage

gpx-to-map <gpx-folder> <output-file> [OPTIONS]

Options

Examples

# Interactive map with default dark style
gpx-to-map ./rides output.html

# Light basemap, steelblue tracks, highlight the latest ride
gpx-to-map ./rides output.html --style light --color steelblue

# Export a static PNG instead
gpx-to-map ./rides output.png --style voyager --color "#e07b39"

# Don't highlight the latest track
gpx-to-map ./rides output.html --no-highlight-latest

How it works

1. Every .gpx file in the folder is converted to GeoJSON via geojson-transformer.
2. All tracks are loaded into an in-memory DuckDB database using the spatial extension.
3. HTML output — renders an interactive lonboard / deck.gl PathLayer map and saves it as a self-contained HTML file.
4. PNG output — plots the tracks with matplotlib and overlays map tiles via contextily, then saves a high-resolution raster image.

The latest GPX file is always loaded into a separate layer so it can be highlighted. "Latest" is determined by the timestamp of the first trackpoint (<trkpt><time>) recorded in the file; files without trackpoint timestamps (e.g. manually-planned routes) fall back to their filesystem modification time.

Python API

create_map can be called directly from Python without the CLI:

from pathlib import Path
from gpx_to_map.core import create_map

create_map(
    gpx_folder=Path("./rides"),
    output_file=Path("output.html"),   # or "output.png" for a static image
    style="dark",                       # "dark" | "light" | "voyager"
    color="steelblue",
    highlight_latest=True,
    geojson_folder=Path("./geojson"),  # optional: keep intermediate GeoJSON files
)

All parameters correspond directly to the CLI options. style accepts the same string values as --style.

Development

git clone https://codeberg.org/marioangst/winti-zh-gpx
cd gpx-to-map
uv sync
uv run gpx-to-map --help