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