Update 2025-07-25: See https://coursepointer.app for a preview WebAssembly-powered version that runs in the browser.
A command-line tool and library that converts GPX routes/tracks and waypoints into Garmin FIT course files with course points. This lets your waypoints appear in Up Ahead on compatible Garmin watches and bicycle computers, showing the distance remaining (and on some devices, estimated time) to reach them.
This provides a way to author courses in third-party applications that don't export to course points, while still using Up Ahead functionality as though the course had been created in Garmin Connect.
The library also offers some lower-level features for building arbitrary FIT courses. See the API docs for details.
When planning a hiking route on Gaia GPS, you can put a route and waypoints together in a Saved Items folder and then export the entire folder as a GPX file:
Run coursepointer on the GPX download to produce a FIT file:
% coursepointer convert rancho-wildcat.gpx
Converted course "Rancho Wildcat" of length 3.03 mi
Processed 5 waypoints, 5 of which were identified as course points:
- Wildcat loop at 1.09 mi along the course
- Vista point at 1.68 mi
- Toilets at 2.70 mi
- Drinking water at 2.74 mi
- Deer Hollow Farm at 2.82 mi
Output is in /Users/mshroyer/Desktop/rancho-wildcat.fit
Copy the FIT file to the device over USB, or import it into Garmin Connect and then send it to your device from the Garmin mobile app. Then, when navigating the course, your course points will appear in Up Ahead on compatible devices:
There are Windows and macOS (universal) binaries in the latest GitHub release, but you'll probably get Windows SmartScreen or macOS Gatekeeper messages you'll have to work around when running them, as they're currently unsigned.
Alternately, to build the latest release from source, install a Rust toolchain with rustup and then run:
cargo install --locked -F cli coursepointer
On your command line, run coursepointer help for usage information.
You can also clone and build this repository for the very most recent version, of course. See docs/development.md for more information.
GPX waypoints specify a latitude, longitude, and optionally elevation. Waypoints can be included in the same GPX file as a route or a track, but that doesn't mean they're necessarily located along the route.
In contrast, the course points in a FIT course file are specifically points on the course. In addition to their latitude and longitude, they also specify the distance at which they appear along the course, which is used by the Up Ahead feature to compute distance remaining.
So given a GPX route and a set of waypoints, coursepointer:
- Identifies which waypoints intercept the route within a configurable threshold distance
- Calculates that point of interception's distance along the total route
- Exports the route and these course points in FIT format
This amounts to solving the interception problem between waypoints and the geodesic segments comprising the route. See docs/Course Point Distances.pdf for more information about the method used here.
As of around 2025-07-13, you can!
Previously, importing a GPX file with a route and waypoints into Garmin Connect's web application did convert any waypoints within about 35m of the course into course points. However, at that time it wouldn't compute their distances, instead setting them to zero.
This led to surprising behavior when you'd navigate this course on your device: Your course points would show up at the correct positions on the map, and may appear in Up Ahead before you begin. But as soon as you'd start recording your course and pass distance zero, they would all disappear!
This was a longstanding limitation that has been discussed on Reddit and in Garmin's forums, and it's what prompted me to create this program to begin with.
Even though Garmin Connect is fixed now, maybe you'll still find coursepointer useful if:
- You want greater control over how course points are interpreted, such as repeating course points or control over the interception threshold
- You'd like something that automatically interprets non-
genericcourse point types in Ride with GPS and Gaia GPS exports - You want to generate course points offline
This should work with GPX routes or tracks and waypoints authored in arbitrary route-planning applications.
However, for routes or tracks exported by Gaia GPS or
Ride with GPS, coursepointer additionally attempts
to map the waypoint or POI type (respectively) to a relevant course point type
instead of generic, so that you'll see a meaningful course point icon
instead of a generic pin. See docs/point_types.md for
more information about how point types from these apps are interpreted as
course point types.
Currently, GPX input files must contain exactly one route or track, and zero or more waypoints. Routes and tracks are treated identically.
In Gaia GPS, archived items in a folder are still included in your folder's GPX export. If you had an old route that you archived and replaced with a new one, the old route may still be getting exported.
To fix this, permanently delete it and then re-export. To avoid it, move routes or waypoints out of your folder before archiving them.
See docs/development.md.
This program relies on a lot of other open source software, but particularly Charles Karney's GeographicLib. Thanks!