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

Let's assume you have a folder of gpx files ./rides.

# 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 over an OpenFreeMap vector basemap (MapLibre GL) and saves it as a self-contained HTML file. On the dark and light styles the basemap's place-name labels are stripped by default (pass --show-names to keep them).
4. PNG output — plots the tracks with matplotlib and overlays no-key Esri raster tiles via contextily (fetched one zoom level deeper than the default for sharpness — tunable with --detail), then saves a high-resolution raster image. The dark style darkens the tiles toward black so the tracks stand out.

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.

Basemaps & attribution

HTML maps use free, no-API-key vector basemaps from OpenFreeMap. OpenFreeMap is run as a public good with no usage limits — if you find it useful, please support it via GitHub Sponsors.

PNG maps use no-key raster tiles from Esri. Keep the on-map attribution visible in anything you publish.

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/gpx-to-map
cd gpx-to-map
uv sync
uv run gpx-to-map --help