gpx-to-map 0.1.0__tar.gz

gpx_to_map-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+.pytest_cache/
+
+# Virtual environments
+.venv
+
+/exports/
+/data/
+
+.env

gpx_to_map-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mario Angst
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gpx_to_map-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: gpx-to-map
+Version: 0.1.0
+Summary: Convert a folder of GPX files into an interactive HTML map or a static PNG.
+Project-URL: Homepage, https://codeberg.org/marioangst/winti-zh-gpx
+Project-URL: Repository, https://codeberg.org/marioangst/winti-zh-gpx
+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/winti-zh-gpx/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/winti-zh-gpx
+cd gpx-to-map
+uv sync
+uv run gpx-to-map --help
+```

gpx_to_map-0.1.0/README.md

@@ -0,0 +1,86 @@
+# 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/winti-zh-gpx/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/winti-zh-gpx
+cd gpx-to-map
+uv sync
+uv run gpx-to-map --help
+```

gpx_to_map-0.1.0/gpx_to_map/__init__.py

@@ -0,0 +1,3 @@
+"""gpx-to-map: Convert a folder of GPX files into an interactive HTML map or a static PNG."""
+
+__version__ = "0.1.0"

gpx_to_map-0.1.0/gpx_to_map/cli.py

@@ -0,0 +1,117 @@
+"""Typer-based CLI for gpx-to-map."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from loguru import logger
+
+from .core import create_map
+from .styles import Style
+
+app = typer.Typer(
+    name="gpx-to-map",
+    help=(
+        "Convert a folder of GPX tracks into an interactive HTML map "
+        "or a static PNG image."
+    ),
+    add_completion=False,
+)
+
+
+@app.command()
+def main(
+    gpx_folder: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            readable=True,
+            help="Folder containing the .gpx files.",
+        ),
+    ],
+    output_file: Annotated[
+        Path,
+        typer.Argument(
+            help="Destination file. Use .html for an interactive map or .png for a static image.",
+        ),
+    ],
+    style: Annotated[
+        Style,
+        typer.Option(
+            "--style",
+            "-s",
+            help="Background map style.",
+            case_sensitive=False,
+        ),
+    ] = Style.dark,
+    color: Annotated[
+        str,
+        typer.Option(
+            "--color",
+            "-c",
+            help=(
+                "Track color. Accepts any matplotlib color name (e.g. 'steelblue'), "
+                "a hex string (e.g. '#1f77b4'), or an RGB tuple (e.g. '31,119,180')."
+            ),
+        ),
+    ] = "red",
+    highlight_latest: Annotated[
+        bool,
+        typer.Option(
+            "--highlight-latest/--no-highlight-latest",
+            help=(
+                "Highlight the most recent track with a contrasting accent color. "
+                "Recency is determined by the first trackpoint timestamp recorded "
+                "in each GPX file (<trkpt><time>). "
+                "File modification time is used as a fallback for files that "
+                "contain no trackpoint timestamps (e.g. manually-planned routes)."
+            ),
+        ),
+    ] = False,
+    geojson_folder: Annotated[
+        Path | None,
+        typer.Option(
+            "--geojson-folder",
+            help=(
+                "Keep the intermediate GeoJSON files in this folder. "
+                "The folder is created if it does not exist. "
+                "Omit this option (the default) to discard the files after the run."
+            ),
+            file_okay=False,
+            dir_okay=True,
+            writable=True,
+        ),
+    ] = None,
+    dpi: Annotated[
+        int,
+        typer.Option(
+            "--dpi",
+            help="Resolution for PNG output in dots per inch. Has no effect on HTML output.",
+            min=50,
+        ),
+    ] = 200,
+) -> None:
+    suffix = output_file.suffix.lower()
+    if suffix not in {".html", ".png"}:
+        logger.error(
+            f"Output file must end in .html or .png — got '{output_file.name}'."
+        )
+        raise typer.Exit(code=1)
+
+    try:
+        create_map(
+            gpx_folder=gpx_folder,
+            output_file=output_file,
+            style=style,
+            color=color,
+            highlight_latest=highlight_latest,
+            geojson_folder=geojson_folder,
+            dpi=dpi,
+        )
+    except (ValueError, FileNotFoundError, NotADirectoryError) as exc:
+        logger.error(str(exc))
+        raise typer.Exit(code=1) from exc