Animated Watercolour Map for Cycle Tour/Race Videos

Introduction
I always record GPS traces of my cycle expeditions, as well as often recording videos, so when I go somewhere interesting I like to combine the two when I get back home. After coming across Stamen's beautiful watercolour maps, I knew that I had found the missing ingredient. My process now is twofold, I use a Python script to retrieve the map and plot the GPS trace to an image, then I overlay and animate the images in a video editor. I have tried to write a guide that will be easy to follow for both the novice python programmer as well as the novice video editor.

The python code is definitely not the most streamlined, because I have focused on readability and cutting the process into discrete steps, once you know how it's done it will be very easy to modify it to your own needs. Everything is done using standard modules.

If you already know how to generate a map image and an trace image, then jump ahead to step 8 (or if you just want the complete script, head to the previous step)

Licensing
All of the software that I used is free/open source. The maps from Stamen are licensed under creative commons. Please don't abuse them by trying to download the entire world at maximum zoom. Obviously you need to license you video accordingly, contact Stamen before using them commercially.

Software Used

• Endomondo (for recording GPS tracks)
• Scripting: Python
• Text Editor
• Image Editor: GIMP
• Video Editing: Kdenlive (can anybody recommend a good free windows option that supports masking?)

Example

Animated GPS Trace Demo from Jason Suter on Vimeo.

Step 1: Starting with Python, Reading in Data

Create the Script
First of all, make sure that you have python installed by typing "python" in a command line window. If you don't, head here. I have tested the script with version 2.7.1

Create a project folder a make a new text file in it that will be your script, I called mine "overlay.py". Open your file with a text editor like gedit (Ubuntu) or Notepad++ (Windows). Regular notepad will work too, but you won't have any syntax highlighting.

Import the Data

Our first objective is to import the GPS trace as a simple list of lat,lon pairs. There are number of formats for storing GPS traces, but I will just deal with comma-separated values (CSV)  and GPS eXchange Format (GPX) because there are plenty of tools to convert almost any format to any other one (GPSVisualiser, is my favourite online converter).

A CSV file can then be easily read in to a python list with the following simple function which makes use of Python's built in "csv" module.

def traceImportCSV(fname):

    import csv
    trace = []
    for lat,lon in csv.reader(open(fname,'r')):
        trace.append([float(lat),float(lon)])
    return trace

Most sites/devices have the option to save routes as GPX (such as Endomondo's export function), so if we can read in a GPX file directly that would be handy. The following bit of code reads the file line by line and uses regular expressions to look for text that says "lat=" or "lon=" and  retrieves whatever non-whitespace characters fall between the following quotation marks.

If both are found on one line, then that lat,lon pair is added to the list. For simplicity the only unusual condition that I have handled is having lat,lon appear as lon,lat instead. If the flags are on different lines, or the file contains items that are not track points, strange results may occur.

def traceImportGPX(fname):

    import re
    trace = []

    for line in open(fname,'r'):
        matchLat = re.search(r'.* lat=\"(\S*)\".*',line)
        matchLon = re.search(r'.* lon=\"(\S*)\".*',line)               
        if matchLat != None and matchLon != None:
            lat = matchLat.group(1)
            lon = matchLon.group(1)
            trace.append([float(lat),float(lon)])

    return trace 

Comments

[dreamberry]

Very cool animation. I can't imagine trips like that on a motorcycle, but pedaling all the way? You da man!

[ossum]

Haha, thanks, that first trace was only about 90km, I guess scale is hard to tell.
The technique could be used on motorcycle/car road trip videos too. In fact, you dont even need a gps, just export the route from google earth.