Usage¶
Once installed, invoke the command line script as gpxtable.
$ gpxtable --help
usage: gpxtable [-h] [--departure DEPARTURE] [--ignore-times] [--speed SPEED]
[--html] [--metric] [--coordinates] [--config CONFIG] [--dump-config]
input [input ...]
positional arguments:
input input file(s)
optional arguments:
-h, --help show this help message and exit
--departure DEPARTURE
set departure time for first point (local timezone)
--ignore-times Ignore track times
--speed SPEED set average travel speed
--html output in HTML, not markdown
--metric Use metric units (default imperial)
--coordinates Display latitude and longitude of waypoints
--config CONFIG config file
--dump-config dump current config and exit
The output is a human-readable markdown-format table which may be included in published information about the trip. Additionally, gpxtable can produce HTML format output using the –html option.
Background and limitations¶
GPX files contain three types of data, waypoints, tracks, and routes.
Tracks consist of one or several ordered lists of latitude/longitude track points. These points on a track are typically close together but do not contain any information suitable for routing or contain any information about points of interest along a “track.” Tracks were originally designed as simple “breadcrumbs” of where a GPS had gone, or may be used to project where one will be going. Tracks typically have no routing information and provide no guidance.
Waypoints are independent points of interest in a GPX file. They are not necessarily associated with tracks or routes at all, they are just pins in the map and have no ordering. They are not associated with any route or track.
Routes are an ordered list of route points describing a straight-line path between each route point. Route points may be via/shaping points which are typically used just for route calculations, or stops which are announced by the navigator. Routes have a major problem, they provide just enough information for the GPS to calculate a route, but each GPS vendor, and in fact, each map version from the same vendor, may alter the routing. There is no uniformity and no guarantee that the route will be identical to what the author intended.
For that reason, most authors prefer to distribute GPX tracks over routes.
Note
Garmin produced extensions to GPX format to include a track segment linking each route point, and the ability to specify layover times at route points, which truly is the best of all worlds. However, even a modern Garmin GPS may recalculate a route from scratch if one goes off-route.
Example: Building a table from a Route (as produced by Basecamp)¶
In this example, we have used sample data to produce the most accurate output as intended by the route author. The author specified delays and layovers in the route configuration itself in Basecamp. These may be overridden with the flag –ignore-times if desired, in which case gpxtable will calculate new times based upon the –departure and –speed options.
* Garmin Desktop App
* Default speed: 30.00 mph
## Route: Fort Ross Run
| Name | Dist. | GL | ETA | Notes
| :----------------------------- | ------: | -- | ----: | :----
| Peet's Coffee Northgate Mall | 0 | | 09:15 | Restaurant
| Nicasio Square | 12 | | 09:39 | Restroom (+0:15)
| Pat's International | 65 | L | 11:41 | Restaurant (+1:00)
| 76 Gureneville | 65/65 | G | 12:41 | Gas Station (+0:15)
| Willy's America | 79 | | 13:23 | Scenic Area (+0:05)
| 76 Bodega Bay | 67/132 | G | 15:14 | Gas Station (+0:15)
| Point Reyes Station | 165 | | 16:36 | Restroom (+0:05)
| Starbucks Strawberry Village | 63/195 | | 17:41 | Restaurant
* 07/30/23: Sunrise: 06:11, Starts: 09:15, Ends: 17:41, Sunset: 20:20
Building a table from a track and waypoints¶
In this example, we have only track and waypoint information.
gpxtable will match waypoints to the provided GPX tracks on a best effort basis. (Unlike GPX routes, tracks don’t embed waypoints).
A –departure command line option should be specified to set the departure time of the tracks. If there are multiple tracks in the GPX file, the program will assume a track per day (use track segments to break up tracks).
Layover delays at waypoints may be automatically added based upon the waypoint symbol type or by including keywords in the waypoint name.
Restaurant: 1 hour (Restaurant | Lunch | Breakfast | Dinner| (L)) Gas Station: 15 minutes (Gas | Fuel | (G)) Restroom: 15 minutes (Restroom | Break | (R)) Photo: 5 minutes (Scenic Area | Photos? | (P)) Scenic Area: 5 minutes
* Garmin Desktop App
* Default speed: 30.00 mph
## Route: Fort Ross Run
| Name | Dist. | GL | ETA | Notes
| :----------------------------- | ------: | -- | ----: | :----
| Peet's Coffee Northgate Mall | 0 | | 09:15 | Restaurant
| Nicasio Square | 12 | | 09:39 | Restroom (+0:15)
| Pat's International | 65 | L | 11:41 | Restaurant (+1:00)
| 76 Gureneville | 65/65 | G | 12:41 | Gas Station (+0:15)
| Willy's America | 79 | | 13:23 | Scenic Area (+0:05)
| 76 Bodega Bay | 67/132 | G | 15:14 | Gas Station (+0:15)
| Point Reyes Station | 165 | | 16:36 | Restroom (+0:05)
| Starbucks Strawberry Village | 63/195 | | 17:41 | Restaurant
* 07/30/23: Sunrise: 06:11, Starts: 09:15, Ends: 17:41, Sunset: 20:20
Limitations:
A waypoint will be matched with the nearest point on it track, if a track doubles-back on itself, it’s difficult to tell if a waypoint is on the outbound or inbound leg.
A pseudo-waypoint will be added indicating the last point in the track. If this is redundant with the final waypoint, it will not be added.
Waypoint Classifer¶
The command line version of this program adds the ability to either print the current waypoint classifier configuration and exit, or to load a replacement classifier.
The –config command takes a JSON file as an argument. This file contains parameters for classifying different waypoints and how they should be treated. See the API documentation for the format of these values.
The –dump-config display what it thinks is our current configuration (either the default configuration or one loaded by –config and then exit.
[
{
"delay": 75,
"fuel_reset": true,
"marker": "GL",
"search": "(?=.*\\b(Gas|Fuel)\\b)(?=.*\\b(Lunch|Meal)\\b)",
"symbol": "Gas/Restaurant"
},
{
"delay": 15,
"fuel_reset": true,
"marker": "G",
"search": "\\bGas\\b|\\bFuel\\b|\\b\\(G\\)\\b",
"symbol": "Gas Station"
},
{
"delay": 60,
"marker": "L",
"search": "\\bRestaurant\\b|\\bLunch\\b|\\bBreakfast\\b|\\b\\Dinner\\b|\\b\\(L\\)\\b",
"symbol": "Restaurant"
},
{
"delay": 15,
"search": "\\bRestroom\\b|\\bBreak\\b|\\b\\(R\\)\\b",
"symbol": "Restroom"
},
{
"delay": 5,
"symbol": "Scenic Area"
},
{
"delay": 5,
"search": "\\bPhotos?\\b|\\b\\(P\\)\\b",
"symbol": "Photo"
}
]