geotag.py

geotag.py reads a GPS track file (in GPX format) and a .JPG picture (or pictures). By comparing timestamps, it determines where the pictures were taken, and writes the GPS coordinates to the picture's GPSInfo EXIF tags. It also outputs a new GPX file containing a waypoint for each picture.

History

My first geotagging experience was with a program called gpsphoto. It worked very well, but dealt only with gpspoint files. At the time (pre-Google Earth) that was fine, but now that I've switched to GPX, I needed something different. There are a number of programs available to do this, but most are Windows- or Mac-only. I found a few with source on the net: Jamie Lawrence's PhotoPlanet.py and Seth Goleb's geocoding software. I used these as a starting point to put together geotag.py. Witness the power of open source! :)

Requirements

  • Python (I use version 2.4.2, probably works with other versions)
    • pyxml is recommended, but shouldn't be required (if you use Gentoo, you can emerge pyxml)
  • EXIF.py. I've included a copy for convenience, but you can download the latest version using the link. You don't need to install it, you can just put it in the same directory as geotag.py
  • exiv2. This is the program that actually writes the EXIF tags.

I use Linux on an Intel machine. All this software is available for Windows, and this program should work on Windows, though I haven't tested it.

Download

Download the script here.

Preparing to use it

It's easiest if the clock on your GPS is in sync with your camera clock. The closer in sync, the more accurate the GPS information that will be output. If you discover that there's a discrepancy, you can adjust the pictures after-the-fact using exiv2. The following example adds 12 hours, 14 minutes, and 1 second to all the .JPG files in a directory:

exiv2 -a 12:14:01 adjust *.JPG

You don't need to worry about the timezone at this stage; geotag.py provides a way to deal with that.

Usage

Basic usage is geotag.py [options] [photo1 photo2 ...]

options are:

  • -g FILE or --gps=FILE points to the GPX track file (this is required)
  • -p DIR or --photos=DIR points to a directory containing .JPG (or .JPEG) files. You can omit this argument and specify individual files as well.
  • -t TIMEDIFF or --timediff=TIMEDIFF specifies how you want to adjust the times on the JPEG files. My GPS records time in UTC, and my camera in local time, so if I'm hiking in the eastern U.S. during the winter (as I normally do), or in Eastern Standard Time, I would specify --timediff=5. This adjusts the JPEG times by adding 5 hours, so that they match the GPS times. The time is not actually changed within the picture files; the calculation is just used within geotag.py
  • -o FILE or --output=FILE points to the output GPX file. One waypoint is written for each picture that is located. If not specified, the output is written to standard out.
  • -u or --update-photos instructs geotag.py to actually write the GPS information to the photos. If omitted, the photos are not touched.

You can specify individual .JPG files after the options, but it's probably easier to specify a directory containing pictures.

Here's an example:

geotag.py --gps=20061220_citrus_track.gpx --photos=/storage/pictures/20061220_citrus_photos --timediff=5 --update-photos --output=20061220_citrus_track.gpx

This reads the trackfile 20061220_citrus_track.gpx taken from my Citrus Trail hike, reads photos from the /storage/pictures/20061220_citrus_photos directory (adding 5 hours to the photos when looking for a match), and updates the photos with the GPS information it finds. An output waypoint file is written to 20061220_citrus_track.gpx.