pherotrails 0.1.0a1

Hive-like sports activity visualizer

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 (recommended) or pipx.

• Install ffmpeg 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.

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:

export MAPBOX_TOKEN="<your token here>"

Usage

Obtain your data

• Go to "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

uvx pherotrails [ARGS]

# or, with pipx:
pipx run --pip-args="--pre" pherotrails [ARGS]

A typical run looks like:

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:

uv run pherotrails [ARGS]

Formatting and linting

Currently manual only, therefore mandatory 😇

uvx ruff format . && uvx ruff check --extend-select I --fix .
uvx mypy --ignore-missing-imports .