Your workout route (in three dimensions!)

Screenshot of a 3D linechart that represents a workout route. X, Y and Z dimensions are latitude, longitude and elevation. All chart decoration has been removed. The route is circular; the southern horizontal portion has low elevation and there is a great deal of elevation to the north. The angle of the chart has been changed to show the view from the south-west. A small emoji runner is placed at the highest point.

tl;dr

You can use R to extract coordinate and elevation data from a GPX file and then plot it as an interactive 3D object. I put some functions in the tiny R package {gpx3d} to help do this.

Elevate to accumulate

I’ve seen recently on Twitter some people using Marcus Volz’s {strava} R package to create pleasing visualisations of their running routes as small-multiples.

I don’t use Strava, but I downloaded my Apple Health data this week and it contained a folder of GPX files; one for each ‘workout’ activity recorded via my Apple Watch.1 GPX files are basically just a type of XML used for storing GPS-related activity.

But rather than try to emulate {strava}, I thought it might be ‘fun’ to incorporate the elevation data from a GPX as a third dimension. I’ve also had mikefc’s {ggrgl} package—‘a 3D extension to ggplot’—on my to-do list for a while now.

An alternate dimension

Cut to the chase: I made a tiny package called {gpx3d}. For now it does what I want it to do and it works on my machine.

You can download it from GitHub with help from the {remotes} package.

install.packages("remotes")  # if not yet installed
remotes::install_github("matt-dray/gpx3d")

There are a number of dependencies, including many that are not available on CRAN; see the README for {ggrgl} for details. You must also install XQuartz, if you haven’t already.

The package does two things and has two exported functions:

  • extract_gpx3d() gets the data out of a GPX file (i.e. it reads a GPX file; parses the XML; extracts datetime, latitude, longitude and elevation; converts to sf-class; and calculates the distance covered)
  • plot_gpx3d() plots the data as an interactive 3D object (i.e. it takes the output from extract_gpx3d(), generates a ‘3D ggplot’ using {ggrgl} and renders it as an interactive object to an external device)

There are also two demo datasets:

  • segment.gpx, a GPX file containing a shorter, edited version of the route used in this blogpost, which you can access with system.file("extdata", "segment.gpx", package = "gpx3d") after installing the package
  • gpx_segment, an sf-class data.frame that’s the result of using the extract_gpx3d() on the built-in segment.gpx file

Read on for an explanation and examples.

Extract

There are already functions that can help read GPX files into R, like gpx::read_gpx() and plotKML::readGPX(), but I decided to do it by hand with {xml2} to get a custom output format (and to practice handling XML).

In short, the extract_gpx3d() function uses read_xml() to read the GPX file, then as_list() to convert it to a deeply nested list. A little wrangling is then required to create a data.frame: datetime and elevation can be hoisted out of the list okay, but the longitude and latitude are actually extracted from the attributes.

After this, the data.frame is converted to the ‘geography-aware’ sf-class.2 I’ve done this for two reasons: (1) the output object can be taken away and will play nicely with various {sf} functions, letting you create various maps and perform further processing, and (2) it allowed me to calculate the distance between each recorded point, which could be summed for total distance.

To use extract_gpx3d(), simply pass a path to a GPX file. I’ve chosen a 10 km run I took on Christmas morning,3 which I downloaded from Apple Health and stored locally.4

file <- "~/Downloads/apple_health_export/workout-routes/route_2021-12-25_9.31am.gpx"
route <- gpx3d::extract_gpx3d(file)
route[2000:2004, ]
## Simple feature collection with 5 features and 5 fields
## Geometry type: POINT
## Dimension:     XY
## Bounding box:  xmin: 0.559015 ymin: 50.85109 xmax: 0.559273 ymax: 50.85109
## Geodetic CRS:  WGS 84
##                     time      ele      lon      lat                  geometry
## 2000 2021-12-25 09:13:29 8.406136 0.559273 50.85109 POINT (0.559273 50.85109)
## 2001 2021-12-25 09:13:30 8.498508 0.559209 50.85109 POINT (0.559209 50.85109)
## 2002 2021-12-25 09:13:31 8.599027 0.559144 50.85109 POINT (0.559144 50.85109)
## 2003 2021-12-25 09:13:32 8.721706 0.559079 50.85109 POINT (0.559079 50.85109)
## 2004 2021-12-25 09:13:34 8.858613 0.559015 50.85109 POINT (0.559015 50.85109)
##          distance
## 2000 4.564465 [m]
## 2001 4.494285 [m]
## 2002 4.564465 [m]
## 2003 4.564465 [m]
## 2004 4.492909 [m]

You can see the rows are basically a measurement per second (time) of the coordinates (lon and lat) and elevation (ele), and that the sf-class metadata and geometry column are present, along with the distance in metres from the previous to current point.

You can take this dataset away and do other stuff with it, like create a lat-long plot of the route (below left), or the elevation over time (below right).

par(mfrow = c(1, 2), mar = rep(0, 4))
with(route, plot(lon, lat, type = "l", axes = FALSE))
with(route, plot(time, ele, type = "l", axes = FALSE))

Two plots: to the left a line showing the route of the run; to the right a line showing the elevation over time. The route is a single loop, roughly rectanglular but with several kinks. The elevation rises before dropping steeply to a plateau, then sharply rising again.

If you’re wondering about the little ‘tail’ in the bottom right of the route, I accidentally joined the back of a Parkrun, so quickly did a hairpin turn to escape. Except the Parkrun route is a ‘there-and-back’ course, so the confused stewards thought I was now in the lead with a pace of about two minutes per kilometre. Whoops!

The elevation plot is pretty dramatic: roughly, it goes downhill to a small plateau, down again to a flatter plateau, then the inevitable (steep!) climb. The lowest plateau is along the seafront, so basically sea level.

But boo! Only two dimensions? You can instead use the plotting function built in to {gpx3d} for something a bit more exciting.

Plot

All the hard work of plotting is done primarily by {ggplot2} and {ggrgl}. The former is probably well-known to readers; the latter is an extension written by mikefc to introduce a third dimension to ggplot objects. In other words, you can extrude your plot along some third variable to generate a z-axis.

There’s a whole bunch of specialised 3D geoms in {ggrgl}. For my purposes, I wanted to extend a geom_path() line plot into the third dimension. This is achieved by adding a z argument to the aes() call of the geom_path_3d() function, where z is our elevation data.

The function renders the plot as an interactive 3D object with {rgl} to an external devoutrgl::rgldev() graphics device. I’ve managed to embed it in the blog below after peeking at mikefc’s vignettes for {ggrgl}, though it may take a moment to load and there’s no guarantees it will work on mobile.

gpx3d::plot_gpx3d(route_sf)

[Mouseclick and drag the object below, or zoom with your scrollwheel]5