top image
home  /  pages  /  tech tips  /  contact about

cuerator: bike ride cue sheets from KML/GPX files


The impatient can immediately download cuerator.

cuerator takes a .gpx or .kml file (that you create at, for example) and creates a cue sheet in PDF format.

Take a look at example output; this is a ride from Cambridge, MA to Mt. Wachusett and back. I generated it from a kml file that I created at

Please note that this is very much an experimental version! It works for me, but it is much less likely that it will work for you.


$ ./cuerator --help

usage: cuerator [--verbose] [--pdf P] [--miles] [--size S] FILE

  --help       : this help
  --miles      : use feet and miles, not meters and kilometers
  --pdf P      : name of pdf output (default directions.pdf)
  --size S     : font size in the PDF (default 10)
  --verbose    : increase verbosity

  FILE         : a .gpx or .kml file


  $ ./cuerator route.kml

Download and Install

You can download cuerator [version 0.1.4, August 30, 2010]. It is distributed under the MIT License. cuerator is a Ruby script that depends on a number of Ruby gems that you can install as follows.

$ gem install geokit
$ gem install prawn

Note that you need to have a working Internet connection to run cuerator.

Issues, Limitations, Questions

How do I create a KML or GPX file in the first place?
At, for example, using the "GPS Export" button. You can also use Google Maps. Once you are satisfied with the route you created in Google Maps, click on the "Link" button at the top right, above the map. Then copy/paste the link into the browser, but append "&output=kml".

Why did cuerator change my route?
It can happen that cuerator changes the route you so carefully planned; but it should only do so on a very small scale. The reason this happens sometimes is that GPX and KML files contain one waypoint for every few meters in the route; in other words, way too many. To deal with that, cuerator tries to quasi-intelligently guess which points it can throw away before generating a route. Sometimes it guesses wrong, resulting in a slighly modified route.

My route is in a different format. Does cuerator support it?
Not currently, no. Let me know what format you use. You can also consider using an online POI converter.

Why is cuerator so slow?
Because—depending on your route—many, many coordinates need to be reverse geolocated. Be patient. The good news is that cuerator creates a local cache that helps, should you choose to regenerate the PDF.

I don't like the metric system; how do I get feet and miles?
Try running with --miles.

What is this file, reverse_geocode.cache?
It is a local copy of reverse-geocoded coordinates in your routes. It helps speed up cuerator. You can throw it away, but it will slow down cuerator.

What if I find a bug?
Please note that cuerator is experimental code. It is very likely you found a bug. Please (fix it and) let me know.


Thanks to Max Poletto for coming up with the name, cuerator.

Copyright © 1994-2011 by Thomer M. Gil
Updated: 2010/04/14