Ridemap - interactive map to visualize GPS tracks

This program allows you to visualize GPS tracks on an interactive map of the world. GPS tracks can be loaded from local GPX files, or fetched via the Strava API. It is written in Rust.

Usage

Basic usage, to display a background map only (see the configuration below):

$ cargo run --release -- \
    --cache-directory cache/ \
    --map-config map-provider.json \
    --lazy-ui-refresh

Loading tracks from local GPX files:

$ cargo run --release -- \
    --cache-directory cache/ \
    --map-config map-provider.json \
    --lazy-ui-refresh \
    gpx \
    --file track1.gpx,track2.gpx

Loading tracks from Strava activities (see the configuration below):

$ cargo run --release -- \
    --cache-directory cache/ \
    --map-config map-provider.json \
    --lazy-ui-refresh \
    strava \
    --strava-config strava-config.json

Advanced usage:

$ cargo run --release -- \
    --cache-directory cache/ \
    --map-config map-provider.json \
    --lazy-ui-refresh \
    --speculative-tile-load \
    --background-ui-thread \
    --parallel-requests 10 \
    --max-pixels-per-tile 512 \
    --max-tile-level 15 \
    strava \
    --strava-config strava-config.json \
    --port 8080 \
    --activities-per-page 50 \
    --activity-pages 12 \
    --activity-count 500 \
    --activity-types ride,hike,swim

Map providers

To display the background map, you need to specify a tiled map provider, that must serve PNG tiles of the world via HTTP addresses of the format https://{server}/{z}/{x}/{y}.{extension}.

Here is an example of map-provider.json file that you pass to the --map-config parameter.

{
    "server": "example.com/tiles",
    "cache_folder": "local/cache/sub/folder",
    "extension": "@2x.png",
    "referer": "https://example.com/",
    "user_agent": "User agent",
}

• The server is the address of the HTTPS tile server, including any sub-folder. It will be prefixed by https://.
• The cache_folder is a sub-folder of the --cache-directory on your disk where tiles for this provider will be cached.
• The extension is a suffix to append to each HTTP query, typically png. Depending on the provider, you can also use it to request larger tiles (via @2x), or pass an access token.
• The referer is an optional value to put in the Referer HTTP header on requests to this tile server.
• The user_agent is an optional value to put in the User-Agent HTTP header on requests to this tile server.

For now, only tiles in PNG format are supported.

Strava API

To automatically fetch GPS tracks from your recent Strava activities, please follow these steps.

First, you need to create a Strava application via your account, following the getting started guide.

From there, copy the client_id and client_secret given to you by Strava, and paste them into a strava-config.json file.

{
    "client_id": "<your client id>",
    "client_secret": "<your client secret>",
}

You can then direct Ridemap to use these API credentials via the --strava-config parameters.

$ ridemap ... strava --strava-config strava-config.json

When running this, Ridemap will print a URL in the terminal output, that you have to click to authenticate a OAuth token to your app for your account and fetch your rides.

Please visit: https://www.strava.com/oauth/authorize?client_id=<client_id>&redirect_uri=http%3A%2F%2F127.0.0.1%3A8080&response_type=code&approval_prompt=auto&scope=read,activity:read_all

Once you click the link and authorize Ridemap, activities will start being fetched and displayed on the map.

Various parameters allow to filter which activities to display, you can list these parameters via the CLI help.

$ ridemap strava --help

Other configuration

The FONT_PATH variable in src/config.rs needs to point to a valid font file on your system. The hard-coded value is a good default on Linux systems.

License

MIT