Skip to content
Tools to turn GPX files into a GPS map tracing layer
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


This is a set of scripts for turning a set of GPS tracks in GPX format into a map tracing layer.


To start out, get a copy of this repository and of datamaps:

$ git clone
$ git clone

If you don't already have it, make sure your system has libxml-parser-perl for XML parsing and libpng-dev and pngquant for generating map tiles

$ sudo apt-get install libxml-parser-perl libpng-dev pngquant

Go into the datamaps directory and compile it:

$ cd datamaps
$ make

Then come back here:

$ cd ../gpx-layer

Extracting points from GPX files

The next step is to extract tracks from your GPX files and index them by location. If you keep your files in ~/gpx, index them into a new datamaps directory called by doing

$ find ~/gpx -name '*.gpx' -print0 | xargs -0 ./parse-gpx | ../datamaps/encode -z20 -m8 -o

The -z20 option means to index with enough precision to draw map tiles at zoom level 20. The -m8 option means that there are 8 bits of metadata (in this case, the direction that the GPS is moving) associated with each entry in the file.

If you keep your GPX files in a directory other than ~/gpx, use the name of that directory instead.

If you already have an old directory, you'll first need to

$ rm -r

to get rid of it before you can index new tracks into it.

Making map tiles

Then it is time to make map tiles out of the data. You can do this with

$ ../datamaps/enumerate -s -z18 | xargs -L1 -P8 ./make-tile

This will take a few minutes if you have a few million points in your GPX files, or hours and hours if you have billions.

If you don't want to go all the way to zoom level 18 (or if you want to go even deeper), you can use a different number instead of -z18. If your computer has more than 8 processors, you can use a different number instead of -P8.

Trying out your map tiles

The previous step will have placed the map tiles into a directory called tiles/

If you the directory you are working in is accessible from a web browser, there is a file called test.html that is already set up to show tiles/ in a web map. (You will probably need to scroll and zoom to see anything, since it doesn't know where your GPS tracks are located and is probably pointed to the wrong part of the earth.)

Otherwise, you'll need to copy the tiles directory to a web server to try it out.

Adding your tiles as a tracing layer in iD

To use your tiles in iD, they really need to be on a web server, and you need to make a copy of iD on the web server (or some other web server) too.

On my home machine, the root directory of the web server is /var/www, so I copied my tiles directory into a directory there called tracing with

$ sudo -s
# rsync -vax tiles /var/www/tracing

Then I also checked out a copy of iD in that directory:

# cd /var/www/tracing
# git clone

The tricky part is that you then have to edit iD's data/imagery.json file to include your new layer.

The simplest thing is to add it like this at the start, right after the opening bracket:

    "name": "GPX overlay",
    "template": "/tracing/tiles/{z}/{x}/{y}.png",
    "overlay": true,
    "scaleExtent": [ 0, 18 ],
    "extent": [ [ -180.00, -90.00 ], [ 180.00, 90.00 ] ]

even though this overstates the area where the layer is relevant. Be sure to include the trailing comma after the closing brace. It's easy to leave off by accident.

You can then open up your modified copy of iD (http://localhost/tracing/iD or wherever you put it instead) in a web browser and turn your new layer on in the Layers popup at the right:

Looking for missing streets

The layer you turn on last draws on top of the other layers, so one nice thing this enables is looking for streets that are missing from the map but are in the GPS logs.

Turn the Locator Overlay off and back on again, and then it looks like this:

with only the GPS tracks that don't quite correspond to streets showing through. In this case, the map of San Francisco is pretty complete, so all that shows through is the ferry route to Sausalito, the Exploratorium pier, and some noise downtown from bad GPS reception.

Using the layer this way is usually practical from zooms 12 to 15, where it is zoomed in enough that the Locator Overlay shows all the streets instead of only the major ones, but not zoomed in enough that iD switches from display to editing.

You can’t perform that action at this time.