pherotrails 0.1.0a1__tar.gz

pherotrails-0.1.0a1/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: pherotrails
+Version: 0.1.0a1
+Summary: Hive-like sports activity visualizer
+Author: Nicola De Mitri
+Author-email: Nicola De Mitri <nicola.dmt@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: cartopy>=0.25.0
+Requires-Dist: gpxpy>=1.6.2
+Requires-Dist: palettable>=3.3.3
+Requires-Dist: pillow>=12.1.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# pherotrails
+
+Your activities, as ant trails 🐜
+
+## Disclaimer
+
+**This is a pre-alpha. ⚠️ It comes with important limitations.**
+
+- It only supports tracks that were recorded directly via the Strava App (`.gpx` files), not those that
+  were imported from other sources such as a Garmin device (`.fit` or other formats).
+
+- Its activity-type filter is limited to just "running" activities.
+
+- **IMPORTANT FOR PRIVACY. IT DOES NOT HIDE** tracks or parts of a track (e.g. the first 200 m) that
+  were marked as "hidden" in Strava.
+
+- Does not honor pause/resume events in Strava. The animation will still show the track as stationary
+  during that time.
+
+## Setup
+
+(Tested on Linux only - but should work on Windows and MacOS too.)
+
+- Please install either [`uv`](https://docs.astral.sh/uv/getting-started/installation/)
+  (recommended) or [`pipx`](https://pipx.pypa.io/stable/how-to/install-pipx/).
+
+- Install [`ffmpeg`](https://www.ffmpeg.org/) and ensure it is in your `PATH`.
+
+### Optional: Mapbox
+
+To use a map as background, you need to have a Mapbox account and generate a token from
+[here](https://console.mapbox.com/account/access-tokens/). 
+
+It's free to sign up, and the free tier allows for 50,000 monthly requests.
+
+Store your token in an environment variable called `MAPBOX_TOKEN`:
+
+```bash
+export MAPBOX_TOKEN="<your token here>"
+```
+
+## Usage
+
+### Obtain your data
+
+- Go to ["delete your account"](https://www.strava.com/athlete/delete_your_account) on Strava.
+  **I know, it sounds scary, but you don't have to actually delete your account.** This is just the page
+  where you can request a copy of your data.
+
+  - Click "Request your archive" and wait for the email from Strava.
+
+  - Once you receive the email, download the zip file and extract it somewhere. You'll need the
+    location of the `activities` folder.
+
+- Define your bounding box. To do so, on Google Maps, click on the bottom-left point of the area you want
+  to visualize and take a note of the latitude and longitude (with sign and with 4 decimal places). 
+  Then click on the top-right point of the area and take a note of its latitude and longitude.
+
+  Your notes should contain something like: `"44.4562,11.2635,44.5430,11.3676"`
+
+  NOTE: some very narrow bounding boxes may not work. Look out for a warning message from Mapbox.
+
+### Run the program
+
+Invoke using 
+
+```bash
+uvx pherotrails [ARGS]
+
+# or, with pipx:
+pipx run --pip-args="--pre" pherotrails [ARGS]
+```
+
+A typical run looks like:
+
+```bash
+uvx pherotrails \
+  --bbox "44.4562,11.2635,44.5430,11.3676" \
+  --data-folder ~/my_strava_data/activities \
+  --activity running \
+  --highlight-circle "17561487369,Bologna Half Marathon 2026" \
+  --output pherotrails_nic_bologna.mp4
+```
+
+### `--help`
+
+The `[ARGS]` are as follows (you can also run `uvx pherotrails --help` to see them):
+
+```
+                   [-h] --bbox S,W,N,E --data-folder DATA_FOLDER --activity ACTIVITY
+                   [--highlight-circle ID,LABEL] [--highlight-square ID,LABEL] [--width PX]
+                   [--background-color R,G,B] [--brush-multiplier VAL] [--time-alignment {start,end}]
+                   [--color-palette {agSunset_7,Fall_6,TealRose_6,Temps_6}]
+                   [--color-code-class {Recency,TotalDuration}] [--color-code-limits MIN,MAX]
+                   [--show-color-legend | --no-show-color-legend]
+                   [--seconds-per-frame SECONDS_PER_FRAME] [--fps FPS] [--extend EXTEND]
+                   [--output OUTPUT] [--use-map-background | --no-use-map-background]
+                   [--unit-system {metric,imperial}]
+
+Render GPS activity tracks as an animated heatmap video.
+
+options:
+  -h, --help            show this help message and exit
+  --bbox S,W,N,E        Bounding box as four comma-separated decimal lat/lon values:
+                        south,west,north,east
+  --data-folder DATA_FOLDER
+                        Path to a folder containing GPX files.
+  --activity ACTIVITY   Activity type to filter for, e.g. "running".
+  --highlight-circle ID,LABEL
+                        Highlight a track with a circle marker. Format: "id,label" (label may contain
+                        commas).
+  --highlight-square ID,LABEL
+                        Highlight a track with a square marker. Format: "id,label" (label may contain
+                        commas).
+  --width PX            Width of the output image in pixels. Height is computed to preserve aspect
+                        ratio. NOTE: to edit feature sizes, use --brush-multiplier instead of changing
+                        the width, as the brush size scales with the width. (default: 1000)
+  --background-color R,G,B
+                        Background color as comma-separated RGB values. (default: 255,255,255)
+  --brush-multiplier VAL
+                        Size multiplier for the brush. Note that there is already a multiplier based
+                        on the total size of the image. The two are compounded. (default: 1.0)
+  --time-alignment {start,end}
+                        How to align tracks in time. (default: TimeAlignment.start)
+  --color-palette {agSunset_7,Fall_6,TealRose_6,Temps_6}
+                        Color palette to use. (default: ColorPalette.Temps_6)
+  --color-code-class {Recency,TotalDuration}
+                        What property to color-code tracks by. (default: ColorCodeClass.TotalDuration)
+  --color-code-limits MIN,MAX
+                        Comma-separated min,max for color coding gradients (in seconds). (default:
+                        1680,3120)
+  --show-color-legend, --no-show-color-legend
+                        Draw an on-screen legend for the color coding used. (default: True)
+  --seconds-per-frame SECONDS_PER_FRAME
+                        How many real-world seconds pass per animation frame. (default: 12.0)
+  --fps FPS             Target frames per second for the output animation. (default: 30.0)
+  --extend EXTEND       Number of frames to add past the last movement. (default: 10)
+  --output OUTPUT       Path for the output video file. (default: pherotrails_output.mp4)
+  --use-map-background, --no-use-map-background
+                        Fetch a map tile to use as background. (default: True)
+  --unit-system {metric,imperial}
+                        Units to display. (default: UnitSystem.metric)
+```
+
+## Developers
+
+### Editable run
+
+From the repository root, run `uv run pherotrails:
+
+```console
+uv run pherotrails [ARGS]
+```
+
+### Formatting and linting
+
+Currently manual only, therefore mandatory 😇
+
+```console
+uvx ruff format . && uvx ruff check --extend-select I --fix .
+uvx mypy --ignore-missing-imports .
+```

pherotrails-0.1.0a1/README.md

@@ -0,0 +1,162 @@
+# pherotrails
+
+Your activities, as ant trails 🐜
+
+## Disclaimer
+
+**This is a pre-alpha. ⚠️ It comes with important limitations.**
+
+- It only supports tracks that were recorded directly via the Strava App (`.gpx` files), not those that
+  were imported from other sources such as a Garmin device (`.fit` or other formats).
+
+- Its activity-type filter is limited to just "running" activities.
+
+- **IMPORTANT FOR PRIVACY. IT DOES NOT HIDE** tracks or parts of a track (e.g. the first 200 m) that
+  were marked as "hidden" in Strava.
+
+- Does not honor pause/resume events in Strava. The animation will still show the track as stationary
+  during that time.
+
+## Setup
+
+(Tested on Linux only - but should work on Windows and MacOS too.)
+
+- Please install either [`uv`](https://docs.astral.sh/uv/getting-started/installation/)
+  (recommended) or [`pipx`](https://pipx.pypa.io/stable/how-to/install-pipx/).
+
+- Install [`ffmpeg`](https://www.ffmpeg.org/) and ensure it is in your `PATH`.
+
+### Optional: Mapbox
+
+To use a map as background, you need to have a Mapbox account and generate a token from
+[here](https://console.mapbox.com/account/access-tokens/). 
+
+It's free to sign up, and the free tier allows for 50,000 monthly requests.
+
+Store your token in an environment variable called `MAPBOX_TOKEN`:
+
+```bash
+export MAPBOX_TOKEN="<your token here>"
+```
+
+## Usage
+
+### Obtain your data
+
+- Go to ["delete your account"](https://www.strava.com/athlete/delete_your_account) on Strava.
+  **I know, it sounds scary, but you don't have to actually delete your account.** This is just the page
+  where you can request a copy of your data.
+
+  - Click "Request your archive" and wait for the email from Strava.
+
+  - Once you receive the email, download the zip file and extract it somewhere. You'll need the
+    location of the `activities` folder.
+
+- Define your bounding box. To do so, on Google Maps, click on the bottom-left point of the area you want
+  to visualize and take a note of the latitude and longitude (with sign and with 4 decimal places). 
+  Then click on the top-right point of the area and take a note of its latitude and longitude.
+
+  Your notes should contain something like: `"44.4562,11.2635,44.5430,11.3676"`
+
+  NOTE: some very narrow bounding boxes may not work. Look out for a warning message from Mapbox.
+
+### Run the program
+
+Invoke using 
+
+```bash
+uvx pherotrails [ARGS]
+
+# or, with pipx:
+pipx run --pip-args="--pre" pherotrails [ARGS]
+```
+
+A typical run looks like:
+
+```bash
+uvx pherotrails \
+  --bbox "44.4562,11.2635,44.5430,11.3676" \
+  --data-folder ~/my_strava_data/activities \
+  --activity running \
+  --highlight-circle "17561487369,Bologna Half Marathon 2026" \
+  --output pherotrails_nic_bologna.mp4
+```
+
+### `--help`
+
+The `[ARGS]` are as follows (you can also run `uvx pherotrails --help` to see them):
+
+```
+                   [-h] --bbox S,W,N,E --data-folder DATA_FOLDER --activity ACTIVITY
+                   [--highlight-circle ID,LABEL] [--highlight-square ID,LABEL] [--width PX]
+                   [--background-color R,G,B] [--brush-multiplier VAL] [--time-alignment {start,end}]
+                   [--color-palette {agSunset_7,Fall_6,TealRose_6,Temps_6}]
+                   [--color-code-class {Recency,TotalDuration}] [--color-code-limits MIN,MAX]
+                   [--show-color-legend | --no-show-color-legend]
+                   [--seconds-per-frame SECONDS_PER_FRAME] [--fps FPS] [--extend EXTEND]
+                   [--output OUTPUT] [--use-map-background | --no-use-map-background]
+                   [--unit-system {metric,imperial}]
+
+Render GPS activity tracks as an animated heatmap video.
+
+options:
+  -h, --help            show this help message and exit
+  --bbox S,W,N,E        Bounding box as four comma-separated decimal lat/lon values:
+                        south,west,north,east
+  --data-folder DATA_FOLDER
+                        Path to a folder containing GPX files.
+  --activity ACTIVITY   Activity type to filter for, e.g. "running".
+  --highlight-circle ID,LABEL
+                        Highlight a track with a circle marker. Format: "id,label" (label may contain
+                        commas).
+  --highlight-square ID,LABEL
+                        Highlight a track with a square marker. Format: "id,label" (label may contain
+                        commas).
+  --width PX            Width of the output image in pixels. Height is computed to preserve aspect
+                        ratio. NOTE: to edit feature sizes, use --brush-multiplier instead of changing
+                        the width, as the brush size scales with the width. (default: 1000)
+  --background-color R,G,B
+                        Background color as comma-separated RGB values. (default: 255,255,255)
+  --brush-multiplier VAL
+                        Size multiplier for the brush. Note that there is already a multiplier based
+                        on the total size of the image. The two are compounded. (default: 1.0)
+  --time-alignment {start,end}
+                        How to align tracks in time. (default: TimeAlignment.start)
+  --color-palette {agSunset_7,Fall_6,TealRose_6,Temps_6}
+                        Color palette to use. (default: ColorPalette.Temps_6)
+  --color-code-class {Recency,TotalDuration}
+                        What property to color-code tracks by. (default: ColorCodeClass.TotalDuration)
+  --color-code-limits MIN,MAX
+                        Comma-separated min,max for color coding gradients (in seconds). (default:
+                        1680,3120)
+  --show-color-legend, --no-show-color-legend
+                        Draw an on-screen legend for the color coding used. (default: True)
+  --seconds-per-frame SECONDS_PER_FRAME
+                        How many real-world seconds pass per animation frame. (default: 12.0)
+  --fps FPS             Target frames per second for the output animation. (default: 30.0)
+  --extend EXTEND       Number of frames to add past the last movement. (default: 10)
+  --output OUTPUT       Path for the output video file. (default: pherotrails_output.mp4)
+  --use-map-background, --no-use-map-background
+                        Fetch a map tile to use as background. (default: True)
+  --unit-system {metric,imperial}
+                        Units to display. (default: UnitSystem.metric)
+```
+
+## Developers
+
+### Editable run
+
+From the repository root, run `uv run pherotrails:
+
+```console
+uv run pherotrails [ARGS]
+```
+
+### Formatting and linting
+
+Currently manual only, therefore mandatory 😇
+
+```console
+uvx ruff format . && uvx ruff check --extend-select I --fix .
+uvx mypy --ignore-missing-imports .
+```

pherotrails-0.1.0a1/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "pherotrails"
+version = "0.1.0a1"
+description = "Hive-like sports activity visualizer"
+readme = "README.md"
+authors = [
+    { name = "Nicola De Mitri", email = "nicola.dmt@gmail.com" }
+]
+license = "MIT"
+
+requires-python = ">=3.12"
+
+dependencies = [
+    "cartopy>=0.25.0",
+    "gpxpy>=1.6.2",
+    "palettable>=3.3.3",
+    "pillow>=12.1.1",
+]
+
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+]
+
+[project.scripts]
+pherotrails = "pherotrails.main:main"
+
+[build-system]
+requires = ["uv_build>=0.10.6,<0.12.0"]
+build-backend = "uv_build"

pherotrails-0.1.0a1/src/pherotrails/color_codes.py

@@ -0,0 +1,217 @@
+import enum
+import math
+from abc import ABC, abstractmethod
+from typing import Any
+
+import palettable
+from palettable.cartocolors.diverging import Fall_6, TealRose_6, Temps_6
+from palettable.cartocolors.sequential import agSunset_7
+
+from pherotrails.tracks import TrackDeck
+
+ColorPalette = enum.Enum(
+    "ColorPalette",
+    [
+        ("agSunset_7", agSunset_7),
+        ("Fall_6", Fall_6),
+        ("TealRose_6", TealRose_6),
+        ("Temps_6", Temps_6),
+    ],
+)
+
+#: "Round" step sizes (in seconds) considered when picking spacing for
+#: duration-legend ticks.
+NICE_DURATION_STEPS = sorted(
+    set(
+        multiplier * unit
+        for unit in (1, 60, 3600, 86400)
+        for multiplier in (1, 2, 3, 5, 10, 15, 20, 30)
+    )
+)
+
+
+def _format_duration(seconds: float) -> str:
+    """Format a duration in seconds as a short human-readable label.
+
+    Drops any zero-valued trailing components, e.g. 90 -> "1m 30s" but
+    3600 -> "1h".
+    """
+    sec = int(round(seconds))
+    if sec < 60:
+        return f'{sec}"'
+    elif sec < 3600:
+        m, s = divmod(sec, 60)
+        return f"{m}'" + (f' {s}"' if s > 0 else "")
+    else:
+        h, rem = divmod(sec, 3600)
+        m, s = divmod(rem, 60)
+        return (
+            f"{h}h" + (f" {m}'" if m > 0 or s > 0 else "") + (f' {s}"' if s > 0 else "")
+        )
+
+
+class ColorCode(ABC):
+    #: The track deck being colored. Set by subclasses in __init__.
+    track_deck: TrackDeck
+    #: The palette used to turn a 0-1 fraction into an RGB color.
+    palette: palettable.palette.Palette
+    #: The domain range (in whatever unit the subclass colors by) that maps
+    #: onto the full extent of the palette.
+    limits: tuple[Any, Any]
+
+    @abstractmethod
+    def __init__(
+        self,
+        track_deck: TrackDeck,
+        palette: palettable.palette.Palette,
+        limits: tuple[Any, Any] | None,
+    ):
+        pass
+
+    @abstractmethod
+    def get_base_rgb_for_track(self, track_idx: int) -> tuple[int, int, int]:
+        pass
+
+    @abstractmethod
+    def legend_title(self) -> str:
+        """Give the label to print above the on-screen color legend."""
+
+    @abstractmethod
+    def legend_stops(self) -> list[tuple[Any, str]]:
+        """Give the (value, label) ticks to print along the color legend.
+
+        Values are expected ascending, and to span at least the full range
+        the legend gradient is drawn over (callers may extend the gradient
+        past `limits` to cover the deck's actual extremes; any such
+        extension is expected to be reflected as the first/last stop here
+        too).
+        """
+
+    @abstractmethod
+    def rgb_at_value(self, value: Any) -> tuple[int, int, int]:
+        """Give the RGB color for an arbitrary value on this code's domain."""
+
+    def _rgb_at_fraction(self, fraction_0_to_1: float) -> tuple[int, int, int]:
+        """Give the RGB color at a position along `palette`'s continuous colormap.
+
+        `fraction_0_to_1` is a position within this color code's own `limits`
+        (0.0 == `limits[0]`, 1.0 == `limits[1]`), not within the deck's actual
+        range of values, which may be wider (values outside `limits` should
+        already be clamped to [0, 1] by the caller before reaching here.
+        """
+        fraction = max(0.0, min(1.0, fraction_0_to_1))
+        r, g, b, _ = self.palette.mpl_colormap(fraction)
+        return (int(r * 255), int(g * 255), int(b * 255))
+
+
+class RecencyColorCode(ColorCode):
+    def __init__(
+        self,
+        track_deck: TrackDeck,
+        palette: palettable.palette.Palette,
+        limits: tuple[Any, Any] | None,
+    ):
+        self.track_deck = track_deck
+        self.palette = palette
+        if limits is None:
+            self.limits = (
+                track_deck.tracks[0].start_time,
+                track_deck.tracks[-1].start_time,
+            )
+        else:
+            self.limits = limits
+
+    def get_base_rgb_for_track(self, track_idx: int) -> tuple[int, int, int]:
+        track = self.track_deck.tracks[track_idx]
+        recency_0_to_1 = (track.start_time - self.limits[0]) / (
+            self.limits[1] - self.limits[0]
+        )
+        recency_0_to_1 = max(0.0, min(1.0, recency_0_to_1))
+        r, g, b, a = self.palette.mpl_colormap(recency_0_to_1)
+        return (int(r * 255), int(g * 255), int(b * 255))
+
+    def legend_title(self) -> str:
+        raise NotImplementedError(
+            "No color legend is implemented for RecencyColorCode."
+        )
+
+    def legend_stops(self) -> list[tuple[Any, str]]:
+        raise NotImplementedError(
+            "No color legend is implemented for RecencyColorCode."
+        )
+
+    def rgb_at_value(self, value: Any) -> tuple[int, int, int]:
+        raise NotImplementedError(
+            "No color legend is implemented for RecencyColorCode."
+        )
+
+
+class TotalDurationColorCode(ColorCode):
+    def __init__(
+        self,
+        track_deck: TrackDeck,
+        palette: palettable.palette.Palette,
+        limits: tuple[Any, Any] | None,
+    ):
+        self.track_deck = track_deck
+        self.palette = palette
+        self.limits = (
+            limits if limits is not None else (0, track_deck.max_individual_duration)
+        )
+
+    def get_base_rgb_for_track(self, track_idx: int) -> tuple[int, int, int]:
+        track = self.track_deck.tracks[track_idx]
+        return self.rgb_at_value(track.duration_seconds)
+
+    def rgb_at_value(self, value: Any) -> tuple[int, int, int]:
+        lo, hi = self.limits
+        fraction = (value - lo) / (hi - lo)
+        return self._rgb_at_fraction(fraction)
+
+    def legend_title(self) -> str:
+        return "Track duration"
+
+    def legend_stops(self) -> list[tuple[Any, str]]:
+        """Give (value, label) ticks spanning `limits`, extended to the deck's actual extremes.
+
+        Picks the coarsest "nice" step (from NICE_DURATION_STEPS) that
+        yields 2 to 4 ticks within `limits`, falling back to just the two
+        limit values if none does. If the deck's shortest or longest track
+        falls more than one such step outside `limits`, an extra tick is
+        added for it.
+        """
+        lo, hi = self.limits
+        span = hi - lo
+        if span <= 0:
+            return []
+
+        for step in NICE_DURATION_STEPS:
+            first = math.ceil(lo / step) * step
+            last = math.floor(hi / step) * step
+            if first > last:
+                continue
+            count = int((last - first) // step) + 1
+            if 2 <= count <= 4:
+                stops = [first + i * step for i in range(count)]
+                break
+        else:
+            stops = [lo, hi]
+            step = span
+
+        actual_lo = min(lo, self.track_deck.min_individual_duration)
+        actual_hi = max(hi, self.track_deck.max_individual_duration)
+        if actual_lo < stops[0] - step:
+            stops.insert(0, actual_lo)
+        if actual_hi > stops[-1] + step:
+            stops.append(actual_hi)
+
+        return [(value, _format_duration(value)) for value in stops]
+
+
+ColorCodeClass = enum.Enum(
+    "ColorCodeClass",
+    [
+        ("Recency", RecencyColorCode),
+        ("TotalDuration", TotalDurationColorCode),
+    ],
+)