GPXPosterPrint

Python project to take a GPX recording from an activity (bike ride, run, walk etc) and make an A3 sized poster - a great way to remember an epic day out.

As a note: I leant on Google Gemini for some of this project as I know a little bit of Python but wanted to get it working quicker

Features

• Up to 6 data fields / metrics of your choice at the bottom of the poster
  • Show average speed, elevation gain etc
• If the start & end points are under 100m apart, a single marker is used to indicatemapbox the start / end point. Otherwise, both points are marked
• Uses standard Mapbox map styles, so easy to style the map to your choice of colour, level of detail (roads, POIs etc)
• Easy customisation of font colours in the config file
  • TOML file format validated before processing
• Available as a pre-built Docker container if you don't have Python but do have Docker installed - see Docker

Requirements

• Python 3.11 or newer as the script requiress the tomlib library. I used Python 3.14.5 with these additonal packages installed (via pip):
  • requests
  • reportlab
  • polyline
  • PyMuPDF
• Mapbox account with a valid access token (API Key)
  • The token scope should have three public scopes enabled:
    • Styles: Tiles
    • Styles: Read
    • Fonts: Read
• GPX file and relevant data from your activity
  • The GPX file can be easily exported from Garmin Connect, Strava etc

Note: When setting up a Mapbox account (if you don't already have one), you will be asked for credit card details. There is a free tier for the Static Images API which (currently) provides up to 50,000 requests per month. In development I've used less than 100 requests, so the chances of you being billed are pretty slim unless you make this project availabile publicly and somebody abuses your access token.

Caution

Protect your Mapbox access token like an important password! Do not put it in a public repository or share it with the Internet.

Setup

I have more detail on my blog (including creating the Mapbox access token:)

cxi.org.uk - GPXPosterPrint

The quick instructions:

• Clone the repository into a folder on your PC
• Copy your chosen GPX file into the same folder
• Rename or copy config.sample to config.toml and edit it, adding the relevant data including:
  • Path & name of the GPX file
  • Mapbox API access token
  • Ride details (title, date)
  • Between 1 to 6 ride metadata fields (distance, time, elevation gain, power, average speed etc)

For instance, if you were doing this on Windows (where Python 3 is already installed) from a PowerShell prompt:

mkdir gpxposterprint
cd gpxposterprint
git clone https://github.com/SynapseCarbon/GPXPosterPrint.git .
python3 -m venv venv\
venv\Scripts\activate
pip install -r requirements.txt

If everything is in the same folder (Python script, config.toml), you should be able to run:

py GeneratePoster.py

If you are producing a few posters at the same time, you can now specify the configuration file to use as a parameter. If no filename is provided, config.toml is used as the default

py GeneratePoster.py myconfigfile.toml

The output should look something like:

GPXPosterPrint started
🔄 Initializing layout engine using profile: 'config.toml'
✅ Success: configuration file passed all structural checks!
Registering fonts...
 -> Montserrat-Bold registered successfully.
 -> Inter-Regular registered successfully.
Parsing 16.7MB GPX file...
 -> Loop detected (63.9m gap). Rendering a single start/end marker.
Requesting map from Mapbox API
 -> Success! Unified map tile asset rendered on layout plane.

✅ PDF poster compiled successfully at: myposter.pdf
Converting PDF to high-res PNG via PyMuPDF (300 DPI)...
✅ Generated high-res PNG at: myposter.png

At that point you've hopefully ended up with PDF and PNG files containing your poster ready to print.