A Free Mac and Windows app for animating GPS track logs
As an avid runner and cyclist I like to explore as much of my surroundings as possible. To keep workouts interesting I began a quest to cover every street within reach of my house and expand outwards. While tools like the Strava personal heat map and Mapnik make it easy to see the streets I’ve covered I thought it would be neat to actually create an app that can play back all of my activities (1,800 and counting) on an animated map. The result is RunParticles.
Demo video
Quick Start
Download the executable here for Mac (MD5: d2a0498b2f69fd4af9accb68b6298959).
Download the Windows installer here. (MD5: b781e7dbfaefb9014a2f1a5818f76dbe).
Source code is available on Github.
RunParticles works on Mac OS X 10.8 and higher.
When the application runs for the first time it will display a black and white OpenStreetMap map of Oakland, California. This can be changed using the “Set starting view area” under the “View” menu.
To troubleshoot installation issues refer to the FAQ.
Map Controls
Dragging with the left mouse button scrolls the view. Additionally the arrow keys on the keyboard move the view by a small amount. Holding down the shift key when pressing an arrow moves the view faster.
Zooming in or out is performed using the mouse’s scroll wheel, double-clicking on the map, or pressing the “+” and “-” keys.
Playback
The playback widget shows a time slider, a speed selector, the current time, and typical playback buttons (rewind, reverse, pause, play). By default RunParticles will play back tracks in real time, or “1x.” For things like runs this is typically so slow that no movement will be visible unless the map view is zoomed very far in.
In addition to the playback widget playback can be paused and started using the space bar. The “J” key plays in revere, the “K” key pauses, and the “L” key plays forward.
Adding a track file
Clicking on the “File” > “Add Track File…” menu item will display a file dialog. RunParticles can display FIT files (with the .fit extension) as produced by most newer Garmin devices, Training Center XML files (with the .tcx extension), and GPS Exchange Format files (.gpx) Note: GPX files must include “time” elements for each track point or else the track will not appear on the map.
For more detailed information on how to get track files off of your device and into RunParticles refer to the FAQ.
Selecting a track
After adding a file RunParticles will add all the tracks it contains to the layer list widget and frame up the last-added track’s bounds in the map. On startup RunParticles will be at zero seconds so drag the time slider in the playback widget forward in order to see the track’s path.
Tracks can be selected by clicking on their particle (the white dot) in the map or their entry in the layer list widget. When a track is selected its color will change to yellow and the particle will be highlighted by two concentric yellow circles.
Framing a layer
The view can be made to fit the bounds of one or more selected layers by clicking “Frame selected layers” in the “View” menu or the right-click context menu of the layer list widget.
Lock view to layer
It is possible to lock the camera view so that it follows the current-selected track by right clicking on the track in the layer list widget and clicking “Lock view to layer” or selecting a track and clicking “Lock view to layer” in the “View” menu.
Saving the map
RunParticles supports saving out the list of added track files and the visible area of the map to an XML file. Note that the map does not actually store track points or timing information, just the paths to the .tcx, .gpx, or .fit files that contain them.
A note on track file formats
.FIT and .TCX files are the best formats for bringing tracks into RunParticles. TCX files support the encoding of multiple activities in the same file, so a single file could presumably contain several years worth of runs and bike rides. RunParticles has been tested with .TCX files up to 200MB in size containing over 600 tracks.
RunParticles will import GPX files but they are subject to several limitations:
- The GPX file must contain a “time” element for each track point or else nothing will be displayed.
- The GPX specification makes no provision for recording the “sport” or type of the activity, so the ambiguity will be indicated in the “Sport” column of the layer list widget for tracks that were imported from a .GPX file.
For best results import tracks in .FIT or .TCX format.
Preferences
RunParticles chooses the color it will use to draw each track path by applying a set of pattern matching rules to the track’s sport field. For example, the default preferences will draw any track whose sport matches the pattern “Running” with the color red and any that matches the pattern “Cycling” in blue. The catch-all “*” wildcard pattern will produce a green track.
By default tracks are drawn as lines one-pixel wide. The pattern matching rules can draw cause RunParticles to draw thicker lines up to a width determined by graphics hardware (usually about 4 pixels). Wider lines can exhibit noticeable drawing artifacts at corners.
Other options
- Show OpenStreetMap
- When checked RunParticles will add the OpenStreetMap basemap when loading or creating new maps. This is the default behavior.
- Frame last added layer
- When checked RunParticles will frame the map view to the bounds of a layer when it is added using the “Add track file” item in the File menu.
- Relative paths in map files
- Since map files only store the paths of the track files that they contain and not the actual data, this option makes it easy to create a map from a self-contained directory. When checked this option makes RunParticles save all paths to the track files in a map as relative to the map file itself.
For example, if the map is saved to /tmp/foo/myMap.xml and it references a track file in /tmp/foo/tracks/myRun.fit, the resulting map file will write the path as "tracks/myRun.fit" and one could move the entire “foo” directory to any location in the filesystem and the track would still load properly when opening the map file in RunParticles.
Bugs and feature improvements
Please refer to the RunParticles issue tracker on Github for known bugs and active feature development.