Metadata-Version: 2.5
Name: gpx-to-map
Version: 0.1.1
Summary: Convert a folder of GPX files into an interactive HTML map or a static PNG.
Project-URL: Homepage, https://codeberg.org/marioangst/gpx-to-map
Project-URL: Repository, https://codeberg.org/marioangst/gpx-to-map
Author-email: Mario Angst <mario.angst@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: geospatial,gps,gpx,map,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.12
Requires-Dist: contextily>=1.6.0
Requires-Dist: duckdb>=1.4.1
Requires-Dist: geojson-transformer>=0.0.7
Requires-Dist: gpxpy>=1.6.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: lonboard>=0.13.0
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: pyarrow>=22.0.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# 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.

![example output](https://codeberg.org/marioangst/gpx-to-map/raw/branch/main/img/winti_zh.png)

## Installation

```bash
pip install gpx-to-map
```

## Usage

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

| Argument | Description |
|---|---|
| `gpx-folder` | Directory containing `.gpx` files |
| `output-file` | Destination path — `.html` for interactive, `.png` for static |

### Options

| Option | Default | Description |
|---|---|---|
| `--style` / `-s` | `dark` | Background map style: `dark`, `light`, `voyager` |
| `--color` / `-c` | `red` | Track color — any matplotlib name, hex (`#1f77b4`), or CSS color |
| `--highlight-latest` / `--no-highlight-latest` | disabled | Highlight the most recent track with a contrasting accent color. Recency is determined by the first trackpoint timestamp in each GPX file, falling back to file modification time |
| `--geojson-folder` | *(discard)* | Keep intermediate GeoJSON files in this folder (created if absent) |
| `--dpi` | `200` | Resolution for PNG output in dots per inch; ignored for HTML |

### Examples

```bash
# 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`](https://pypi.org/project/geojson-transformer/).
2. All tracks are loaded into an in-memory [DuckDB](https://duckdb.org/) database using the `spatial` extension.
3. **HTML output** — renders an interactive [lonboard](https://developmentseed.org/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](https://contextily.readthedocs.io/), 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:

```python
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

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