Mac & OS X Research Software Sports Uncategorized

GoPro GPS Overlay

Yesterday I decided to get an action camera. The decision between a Garmin Virb and the latest GoPro is probably a topic for another article, so let’s just get the decision out of the way; I ended up getting the GoPro Hero3+ Black Edition. In fact, if I’d decided to get the Garmin Virb this article wouldn’t even be necessary. Why? Read on.

Firstly, I’ll say that there are various reasons for getting an action camera, one of which is the need to record my daily ride to work. Nearly every day I encounter situations that I’d like to have proof of, should the need arise. Read: motorists that probably shouldn’t be on the road in the first place.


So what is this article about? I work in I.T. for a living and like looking at GPS data for my proper rides. So, that means you may or may not find the stuff below a wee bit technical. That all depends what you’re into. Anyway, for the GPS part of things I use a Garmin Edge 800. With an action camera, it makes sense that having some speed or other performance data on screen with the video – it’s the inner geek in me controlling that, no doubt. The Elite version of the Garmin Virb has built-in GPS which makes it very easy to overlay GPS data on top of videos. However, because I bought a GoPro, this is an option I don’t have. Not out of the box, at least. But surely it can be done, right?

The short answer: yes!

Desired result

When I look at a cycling video I’ve made, I want to see the current speed & GPS track at the same time. Not in separate windows, either – on top of the video.

The search

I started out looking online for a way to do what I wanted. I found a few ways, including some software that looked promising. Unfortunately, the software is built for Windows only – I use a Mac. Stumped again!

Fortunately for me I found a blog called Syntax Candy, run by a guy called Bartek – a programmer based in Poland. I found that he’d already written a Java application to do exactly what I wanted – score! There are other apps that will do the same thing, but they aren’t free.

Now, I’ve done a fair amount of development in the past but never in Java. That meant my system wasn’t setup for Java development. The next step? Give my system the ability to compile and run Java applications.

The process

Here’s what I had to do get my system ready to run Bartek’s application. I can only cover what I did on OS X, sorry – YMMV for Windows. Note that ~ refers to your home directory.

  1. Download and install the Java Development Kit. As I write this, version 8 is the current version – click here to download.

  2. Set the JAVA_HOME variable. This step is dependant on your shell – the default on OS X is bash, although I use Zsh. For bash, edit ~/.bashrc and for Zsh edit ~/.zshrc (create the relevant file if it doesn’t exist). Put this line in the file:

    export JAVA_HOME=$(/usr/libexec/java_home)
  3. Download Apache Maven – it is required when running Bartek’s application. Click here to download.

  4. You can put Apache Maven anywhere, but put it somewhere that makes sense as you’ll need to reference that location later. On my system, the full path to Apache Maven is in ~/Applications/apache-maven–3.2.1.

  5. Get the full path to your Apache Maven location. To do this, open a Terminal window and type the following commands. They will return the full path, substituting ~ for the actual path to your home directory. Note that this example assumes your Apache Path is ~/Applications/apache-maven–3.2.1.

    cd ~/Applications/apache-maven-3.2.1
  6. Copy the path that is returned – mine is /Users/chris/Applications/apache-maven–3.2.1.

  7. Add the path from step 6 to your PATH environment variable. This isn’t strictly required, but it means you can run Apache Maven without entering the full path to the binary. For bash, edit ~/.bashrc, for Zsh edit ~/.zshrc. On my system, the PATH declaration is as follows – yours will be different, but you can see where I’ve added the Apache Maven path.

    export PATH="/Users/chris/Applications/apache-maven-3.2.1/bin:/Applications/MAMP/bin/php/php5.4.25/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/MacGPG2/bin"
  8. Download the GpsVideo application from Bartek’s blog. Click here to read and download.

  9. Extract the application’s archive somewhere. It doesn’t matter where, as long as you can access it via the Terminal.

  10. Open a Terminal window and change to the directory you extracted the application to. Type the following command. This might take a while as Apache Maven needs to download a bunch of files that are required to run the application.

    mvn package
  11. In the same Terminal window, type the following command. You must be in the GpsVideo application’s directory for this to work.
    mvn compile exec:exec

Here is what the contents of the Terminal window should look like (yours may look different depending on themes, etc).

GpsVideo - Terminal Output
GpsVideo – Terminal Output

And here is what the app should look like, when running correctly.

GpsVideo - Application
GpsVideo – Application

That’s it! If you’ve done everything correctly, the GpsVideo application should run after a few seconds.

GPX files

The Garmin Edge cycle computers save GPS and tracking data in FIT format (by default). For the GpsVideo application, the data needs to be in GPX format. This means taking the FIT file and converting it using something like Garmin Connect or rubiTrack. rubiTrack isn’t free, but the trial version’s only limitation is the number of activities you can have. Imported activites can be exported as GPX from there or Garmin Connect very easily.

What does it look like?

Here’s a screenshot of what a video produced by GpsVideo looks like – not bad at all!

GpsVideo - Video Sample
GpsVideo – Video Sample