{"id":13852510,"url":"https://github.com/flopp/GpxTrackPoster","last_synced_at":"2025-07-13T05:33:25.725Z","repository":{"id":41512162,"uuid":"49301348","full_name":"flopp/GpxTrackPoster","owner":"flopp","description":"Create a visually appealing poster from your GPX tracks","archived":false,"fork":false,"pushed_at":"2024-06-02T18:36:48.000Z","size":12063,"stargazers_count":429,"open_issues_count":20,"forks_count":51,"subscribers_count":15,"default_branch":"main","last_synced_at":"2024-11-21T13:13:26.093Z","etag":null,"topics":["gpx","map","poster","running"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flopp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-08T22:57:55.000Z","updated_at":"2024-11-17T13:50:54.000Z","dependencies_parsed_at":"2023-02-08T19:31:28.445Z","dependency_job_id":"41ea352c-705e-4d84-aa4f-63612d454212","html_url":"https://github.com/flopp/GpxTrackPoster","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flopp%2FGpxTrackPoster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flopp%2FGpxTrackPoster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flopp%2FGpxTrackPoster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flopp%2FGpxTrackPoster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flopp","download_url":"https://codeload.github.com/flopp/GpxTrackPoster/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225861626,"owners_count":17535982,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gpx","map","poster","running"],"created_at":"2024-08-04T22:01:23.334Z","updated_at":"2024-11-22T07:30:31.599Z","avatar_url":"https://github.com/flopp.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"![CI](https://github.com/flopp/GpxTrackPoster/workflows/CI/badge.svg)\n[![Format](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)\n![License MIT](https://img.shields.io/badge/license-MIT-lightgrey.svg?style=flat)\n\n# GpxTrackPoster\nCreate a visually appealing poster from your GPX tracks - heavily inspired by https://www.instagram.com/p/Behppx9HCfx/\n\n## Setup\n1. Clone the repository: `git clone https://github.com/flopp/GpxTrackPoster.git`\n2. `cd GpxTrackPoster`\n3. Create virtualenv: `virtualenv -p /usr/bin/python3 venv` or `python -m venv venv`\n4. Activate virtualenv: `source venv/bin/activate`\n5. Install the package: `pip install .`\n6. Install development requirements (only if you want to contribute code!): `pip install -r requirements-dev.txt`\n7. Run `create_poster` (see above)\n8. Deactivate virtualenv: `deactivate`\n\n### Container\nThere is a Dockerfile in this repository, which you can use to run this software.\n1. Build the container: `podman build -f Dockerfile -t gpxtrackposter:latest`\n2. Run the container to build your poster: `podman run --rm -v /my/gpx/files:/gpx --name gpxtrackposter localhost/gpxtrackposter:latest  create_poster --gpx-dir /gpx --output /gpx/poster.svg`\n\n## Usage\nFirst of all, you need directory with a bunch of GPX files (e.g. you can export all your tracks from Garmin Connect with the excellent tool [garmin-connect-export](https://github.com/kjkjava/garmin-connect-export), or use [StravaExportToGPX](https://github.com/flopp/StravaExportToGPX), or use [runtastic](https://github.com/yihong0618/Runtastic), or use [nrc-exporter](https://github.com/yasoob/nrc-exporter) to convert the activities in a Strava or Runtastic or `Nike Run Club` export zip file to GPX or GPX files).\n\nYou will need a little experience running things from the command line to use this script. That said, here are the usage details from the `--help` flag:\n\nGet data from strava is ok now:\n```\ncreate_poster --from-strava strava.json --year 2020 --title \"Running\" \\\n    --athlete \"Florian Pigorsch\" --special 4110886680(strava id)\n```\nOnly you need is change the strava config\n[How to get strava config](https://developers.strava.com/docs/getting-started/)\n\n```\nusage: create_poster [-h] [--gpx-dir DIR] [--output FILE]\n                     [--language LANGUAGE] [--localedir DIR] [--year YEAR]\n                     [--title TITLE] [--athlete NAME] [--special FILE]\n                     [--type TYPE] [--background-color COLOR]\n                     [--track-color COLOR] [--track-color2 COLOR]\n                     [--text-color COLOR] [--special-color COLOR]\n                     [--special-color2 COLOR] [--units UNITS] [--clear-cache]\n                     [--workers NUMBER_OF_WORKERS] [--from-strava FILE]\n                     [--verbose] [--logfile FILE]\n                     [--special-distance DISTANCE]\n                     [--special-distance2 DISTANCE] [--min-distance DISTANCE]\n                     [--activity-type ACTIVITY_TYPE] [--with-animation]\n                     [--animation-time ANIMATION_TIME]\n                     [--heatmap-center LAT,LNG] [--heatmap-radius RADIUS_KM]\n                     [--heatmap-line-transparency-width TRANSP_1,WIDTH_1, TRANSP_2,WIDTH_2, TRANSP_3,WIDTH_3]\n                     [--circular-rings] [--circular-ring-color COLOR]\n                     [--circular-ring-max-distance DISTANCE]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --gpx-dir DIR         Directory containing GPX files (default: current\n                        directory).\n  --output FILE         Name of generated SVG image file (default:\n                        \"poster.svg\").\n  --language LANGUAGE   Language (default: english).\n  --localedir DIR       The directory where the translation files can be found\n                        (default: the system's locale directory).\n  --year YEAR           Filter tracks by year; \"NUM\", \"NUM-NUM\", \"all\"\n                        (default: all years)\n  --title TITLE         Title to display.\n  --athlete NAME        Athlete name to display (default: \"John Doe\").\n  --special FILE        Mark track file from the GPX directory as special; use\n                        multiple times to mark multiple tracks.\n  --type TYPE           Type of poster to create (default: \"grid\", available:\n                        \"grid\", \"calendar\", \"heatmap\", \"circular\", \"github\").\n  --background-color COLOR\n                        Background color of poster (default: \"#222222\").\n  --track-color COLOR   Color of tracks (default: \"#4DD2FF\").\n  --track-color2 COLOR  Secondary color of tracks (default: none).\n  --text-color COLOR    Color of text (default: \"#FFFFFF\").\n  --special-color COLOR\n                        Special track color (default: \"#FFFF00\").\n  --special-color2 COLOR\n                        Secondary color of special tracks (default: none).\n  --units UNITS         Distance units; \"metric\", \"imperial\" (default:\n                        \"metric\").\n  --clear-cache         Clear the track cache.\n  --workers NUMBER_OF_WORKERS\n                        Number of parallel track loading workers (default:\n                        number of CPU cores)\n  --from-strava FILE    JSON file containing config used to get activities\n                        from strava\n  --verbose             Verbose logging.\n  --logfile FILE\n  --special-distance DISTANCE\n                        Special Distance1 by km and color with the\n                        special_color\n  --special-distance2 DISTANCE\n                        Special Distance2 by km and color with the\n                        special_color2\n  --min-distance DISTANCE\n                        min distance by km for track filter\n  --activity-type ACTIVITY_TYPE, --activity ACTIVITY_TYPE\n                        Filter tracks by activity type; e.g. 'running'\n                        (default: all activity types)\n  --with-animation      add animation to the poster\n  --animation-time ANIMATION_TIME\n                        animation duration (default: 30s)\n\nHeatmap Type Options:\n  --heatmap-center LAT,LNG\n                        Center of the heatmap (default: automatic).\n  --heatmap-radius RADIUS_KM\n                        Scale the heatmap such that at least a circle with\n                        radius=RADIUS_KM is visible (default: automatic).\n  --heatmap-line-transparency-width TRANSP_1,WIDTH_1, TRANSP_2,WIDTH_2, TRANSP_3,WIDTH_3\n                        Define three transparency and width tuples for the\n                        heatmap lines or set it to `automatic` for automatic\n                        calculation (default: 0.1,5.0, 0.2,2.0, 1.0,0.3).\n\nCircular Type Options:\n  --circular-rings      Draw distance rings.\n  --circular-ring-color COLOR\n                        Color of distance rings.\n  --circular-ring-max-distance DISTANCE\n                        Maximum distance for scaling the track lengths (in\n                        given units).\n```\n\nExample:\n```\ncreate_poster --from-strava strava.json --type circular\ncreate_poster --type grid --gpx-dir \"my-tracks\" --language \"de\" --year 2015 --title \"Running\" \\\n    --athlete \"Florian Pigorsch\" --special race1.gpx --special race2.gpx --special race3.gpx\n\ncreate_poster --type github --gpx-dir \"my-tracks\" --language \"de\" --title \"Running\" \\\n    --athlete \"Florian Pigorsch\" --special-distance 10 --special-distance2 10 --special-color yellow --special-color2 red\n```\ncreates a nice poster (`poster.svg`) of the GPX tracks in the directory `my-tracks` (see above).\n\n\n### Selection of Tracks\n\n`create_poster` tries to load all GPX files in the specified directory (option `--gpx-dir`).\nTo speed up subsequent executions of the script, successfully loaded GPX tracks are cached in an intermediate format that allows for fast loading; use the option `--clear-cache` to delete these files.\nTracks without time stamps and tracks recorded in the wrong year (option `--year`) are discarded.\nTracks shorter than 1km are discarded, too\nIf multiple tracks have been recorded within one hour, they are merged to a single track.\n\n### Filtering activities `--from-strava FILE` by `activity_type`\n\nWhen using `--from-strava FILE` option,\nyou may specify optional `activity_type` to filter only certain [type(s) of activity][strava-activity-type] to load.\nNote, `activity_type` filters activities only when loading from strava, and will not affect what already cached.\nThat means if you change the value of `activity_type` you have to use `--clear-cache` to reload with the new filter.\nYou can provide `activity_type` with a list or a string.\nAll following examples are valid.\n\n```json\n{\n    \"client_id\": \"YOUR STRAVA API CLIENT ID\",\n    \"client_secret\": \"YOUR STRAVA API CLIENT SECRET\",\n    \"refresh_token\": \"YOUR STRAVA REFRESH TOKEN\",\n    \"activity_type\": \"Run\"\n}\n```\n\n```json\n{\n    \"client_id\": \"YOUR STRAVA API CLIENT ID\",\n    \"client_secret\": \"YOUR STRAVA API CLIENT SECRET\",\n    \"refresh_token\": \"YOUR STRAVA REFRESH TOKEN\",\n    \"activity_type\": [\"Walk\", \"Hike\"]\n}\n```\n\n```json\n{\n    \"client_id\": \"YOUR STRAVA API CLIENT ID\",\n    \"client_secret\": \"YOUR STRAVA API CLIENT SECRET\",\n    \"refresh_token\": \"YOUR STRAVA REFRESH TOKEN\"\n}\n```\n\n## Poster Types\n\nUsing the `--type` command line parameter, you can specify which type of poster to create:\n\n### Grid Poster (`--type grid`)\nThe *Grid Poster* layouts all tracks in a grid, starting with the earliest track in the upper left corner of the poster, continuing with the second earliest track to the left, and so on.\n*Special tracks* are drawn with the selected *special color*.\n*Special distance tracks* are drawn with the selected *special color*.\n\n![Example Grid Poster](https://raw.githubusercontent.com/flopp/GpxTrackPoster/main/examples/example_grid.png)\n[svg](https://github.com/flopp/GpxTrackPoster/blob/master/examples/example_grid.svg)\n\n### Calendar Poster (`--type calendar`)\nThe *Calendar Poster* draws one square for each day, each row of squares corresponds to specific month. If a track was recorded of a day the corresponding square is colored with the *track color* or with the *special color* if the track is marked as special. A day's total track length in kilometers is printed below each square.\n\n![Example Calendar Poster](https://raw.githubusercontent.com/flopp/GpxTrackPoster/main/examples/example_calendar.png)\n[svg](https://github.com/flopp/GpxTrackPoster/blob/master/examples/example_calendar.svg)\n\n### Circular Poster (`--type circular`)\nThe *Circular Poster* the year in a circle; each day corresponds to a circle segment. The length of each segment corresponds to the total track distance of that day.\n\n![Example Circular Poster](https://raw.githubusercontent.com/flopp/GpxTrackPoster/main/examples/example_circular.png)\n[svg](https://github.com/flopp/GpxTrackPoster/blob/master/examples/example_circular.svg)\n\n### Heatmap Poster (`--type heatmap`)\nThe *Heatmap Poster* displays all tracks within one \"map\". The more often a location has been \"visited\" on a track, the more colorful the corresponding location is on the map. *Special tracks* are drawn with the *special color*.\n\n![Example Heatmap Poster](https://raw.githubusercontent.com/flopp/GpxTrackPoster/main/examples/example_heatmap.png)\n[svg](https://github.com/flopp/GpxTrackPoster/blob/master/examples/example_heatmap.svg)\n\n### Github Poster (`--type github`)\nThe *Github Poster* displays all tracks like github profile. *Special distance* are drawn with the *special color*.\n\n![Example Github Poster](https://raw.githubusercontent.com/flopp/GpxTrackPoster/main/examples/example_github.png)\n[svg](https://github.com/flopp/GpxTrackPoster/blob/master/examples/example_github.svg)\n\n\n\n## Selection a Language\n`create_poster` uses gettext to provide localization to other languages.\nTo select a different language than the default English, use the `--language LANGUAGE` option.\nWe currently support\n\n- French (`--language fr_FR`)\n- German (`--language de_DE`)\n- Chinese (`--language zh_CN`)\n- Russian (`--language ru_RU`)\n- Finnish (`--language fi_FI`)\n\n## Contributing\nIf you have found a bug or have a feature request, please create a new issue. I'm always happy improve the implementation!\n\nOr even better: clone the repo, fix the bug/implement the feature yourself, and file a pull request. Contributions are always welcome!\n\nImportant: If you want to contribute via a pull request, make sure you run `make lint` and possibly `make format` and `make update-readme` before pushing code.\n\n## Translation\nThe translation is based on GNUs 'gettext'.\nFor the translation of the month names to work, the language must be installed.\n\nUse `locale -a` to check if the language is installed.\n\nUse `locale-gen ru_RU.UTF-8` to install another language and update the locale `update-locale`.\n\n### Add new translation\nExample:\n`msginit --input=gpxposter.pot --locale=de_DE --output=locale/de_DE/LC_MESSAGES/gpxposter.po`\n\n### Update a translation\nE.g. use [Poedit](https://poedit.net/) or [Localise Online Editor](https://localise.biz/free/poeditor) to edit the \"po\" files.  Afterwards compile that files.\n\n### Create compiled translation file\n`msgfmt gpxposter.po -o gpxposter.mo`\n\n## License\n[MIT](https://github.com/flopp/GpxTrackPoster/blob/master/LICENSE) \u0026copy; 2016-2023 Florian Pigorsch\n\n[strava-activity-type]: https://developers.strava.com/docs/reference/#api-models-ActivityType\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflopp%2FGpxTrackPoster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflopp%2FGpxTrackPoster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflopp%2FGpxTrackPoster/lists"}