darktable article lede image
Geotagging in darktable

Geotagging in darktable

Geotagging module

For quite some time people have asked us for a way to geotag their images from within darktable. While that is a nifty feature for sure and really helpful when you take pictures outside of a studio we always had to say something along the lines of “sorry, we don’t have that yet”. Some day however Henrik decided to give it a try and started work in his geo branch. Things started to come together nicely and everything looked really promising, but unfortunately he was a little short in free time so the progress stalled and the code started to bitrot. Since it would be a pity to throw away all the great work Henrik did I kind of adopted the branch and set sails to add the missing bits and pieces to make geotagging a new feature of darktable.

Granted, a few details are still missing and I wouldn’t be surprised if a few quirks and bugs can be found, too, but nevertheless I decided that the code was ready for prime time and merged it back into master. So everyone using either the experimental builds from Pascal’s PPA, compiles darktable from git or has some other way to run the latest and greatest development version of darktable can try all of this stuff.

A full fledged GPS receiver and a small logger
A full fledged GPS receiver and a small logger

While the easiest way to get geotagged images is using a camera with a built-in GPS receiver (or an external receiver attached to the camera) most people don’t have that. So we somehow have to assign geo locations to the images. Basically there are two ways to do that: for one you can do it manually for every image or you can use a GPS receiver to record a GPX track while you take your pictures (you can either use a cheap GPS logger or a full fledged GPS receiver, maybe even your phone). If you just want to try this you can take the manual route but if you plan to geotag thousand of pictures taken during your vacation I would advice to spend a little money on some hardware.

Some background information

If you are lucky enough to have a camera which already stores coordinates in the EXIF data of the images you can skip this paragraph and also the next one. If you want to tag the images manually you can skip the next two paragraphs, too. Or just keep reading, it might be interesting after all. ;)

So, let me explain the intended workflow to assign geo locations to your images making use of the GPX file stored by your GPS tracker. First of all let me explain what these GPX files are. The GPS receiver calculates its current position based on the information it receives from some satellites and stores them in a GPX file, together with the current date and time (and some other data which we are not interested in). Basically it is a mapping between time and position, telling us where the device has been at a given time. As you probably know, the EXIF data of the images also contains a time stamp. So all we have to do is take the time stamp of the image, look-up the position of the GPS tracker at that point in time and assume that camera and GPS device were in close proximity. Easy. Well, at least in theory. In reality there are a few problems which you need to keep in mind.

First, most cameras don’t have the exact time (GPS devices however have it, they are basically showing the time from atomic clocks sent by the GPS system). At least my camera is almost always off a little. Maybe you are better in taking care of setting the embedded clock. Anyway, if the time of camera and GPS tracker differs the location will also be wrong. So we might need to fix the time stored with the image.

The second problem is more systematical. The time stored in the EXIF data doesn’t contain a time zone. At least on all cameras I have seen so far. So what exactly does a time stamp of “12:00:00” mean? Well, it’s noon, but where? Most people set it to their local time, but what is that? The image doesn’t tell us. All we know is that the GPX file uses UTM time (at least with my Garmin) or contains the time zone used if it doesn’t. In order to correctly find the position of the image we need to know if it’s noon in London (UTM), New York, Berlin, Sydney or any other place of the world.

Adding coordinates to the images

Calculating the time offset
Calculating the time offset

As we have just seen we need to take care of the time in two places: the offset in the images and the time zone needed to make sense of the EXIF data. That is also the order in which you have to tackle them: first the offset, then the time zone. To fix the drift of the camera assigned time stamp you can either enter it manually into the offset input field in the geotagging module in lighttable mode or let darktable help you. All you need is a picture taken of a reliable time source. This can be any precise clock or even better the time displayed on your GPS device – provided it has a display to show you the time. When you have such an image selected you can click on the button next to the offset entry (currently it has a looking glass as its icon, that might change though) and darktable will present you an entry box at the bottom of the window. Just enter the time that is shown on the clock or GPS device that you took a picture of and hit enter (or click OK). As a result you will get the difference between the time you entered and the one associated with the image in its EXIF data entered into the offset field on the right. Now all you have to do is selecting all the images you want to geotag (and that are probably suffering from the same time offset) and click the apply button (currently represented by a check mark). This will alter the time in darktable’s internal database for these pictures, so you will also see the change in the image information module on the left. However, in the current state darktable will NOT attach this changed time to your exported images – they will still use the original value the camera wrote, but that is supposed to change.

Loading a GPX file
Loading a GPX file

Now that you have a bunch of images with a corrected time you can apply a GPX track. Click the corresponding button in the geotagging module and navigate to the GPX file. Before confirming that dialog you should make sure that the time zone selector is showing the right one for your camera. Once that is confirmed you can click on Open. Should you ever make a mistake with the time zone selection you can just come back and reapply the GPX file with a different time zone.

Watching the images on the map

Map mode
Map mode

At this point I suppose that your pictures have a location assigned – either by a nifty camera which does it on its own or by you loading a GPX file – or that you want to add that information manually. In any case you should switch to the map mode by selecting it in the header of the window (top right hand, maybe you have to expand the top panel and/or hit ctrl-h to see it). You should now see a map in the center and some new modules on the right. Make sure to display the film strip on the bottom of the window (expand the bottom panel and/or hit ctrl-f). If your images are already tagged with a location you can now double click them in the film strip and the map will be zoomed to the image. You can also pan the map by clicking and dragging the mouse and zoom it using the mouse wheel (yes, we will add keyboard shortcuts). If you want to geotag an image manually or are not happy with the location that it currently has you can put them on the map by dragging them from the filmstrip and dropping them on the map. Currently it’s not possible to drag them around on the map, you always have to take them from the filmstrip! In order to help you finding the place on earth where you want to put the image to there is a location module on the right hand with which you can search for city names, points of interest, …

TL;DR

First adjust the time offset of the images, then import the GPX file and make sure to use the correct time zone. Drag&drop images from the film strip to the map afterwards when you think that you have to.

Filed under: Upcoming Feature
These are comments from the old website, archived as static HTML
  1. Can you make a video demo?
  2. My Nikon D90 saves the time zone in an Exif tag (doesn't seem to take into account DST, though):

    $ exiftool 20120731_0001.NEF |grep Timezone
    Timezone : +01:00
  3. Torsten Bronger on Mon Sep 24 12:43:47 2012:
    @Gidoca: Yes, but this is Nikon-specific. It is most embarrassing that the EXIF standard cannot store a true timestamp (i.e. timezone infor is lacking).
  4. orbisvicis on Mon Sep 24 16:50:26 2012:
    Looking good! Do you stream the OSM data and render it locally with mapnik, or fetch prerendered tiles from a webserver?
  5. We are using prerendered tiles. There have been a few changes since I wrote this blog post. For example you can now display an OSD on the map and select different map sources (openstreetmap, google maps, virtual earth map/satellite and a few more). This whole feature is pretty much work-in-progress ...
  6. Ladislav Ezr on Thu Sep 27 13:05:43 2012:
    EPIC! You guys rocks! As semi-professional photograper I would like to support the development, but since I cant code I would like to donate some money which I wanted to use for Aftershot and for which I dont have any use now :) (since you can provide this glorious OSS project). So, how can I do that? :F
  7. Hi Ladislav,

    nice to hear that you're enjoying our piece!

    Since we don't have any form of legal organisation behind us we are currently not able to receive donations. We're working on that in the long perspective though...

    But if you still want to help us:
    * Spread the word!
    * Try to contribute in another way, there are many! (Write tutorials, help us with documentation, translate DT into your language...)

    Cheers,
    Simon
  8. Ladislav Ezr on Sun Sep 30 13:32:59 2012:
    > SMN

    As I said before, it would be great if the DONATE button get higher priority ;)

    Anyway, as I'm short on time now the only thing I can do is some translations, fortunatelly DT is fully translated into Czech, but what about the website? Would it be possible to translate it?
  9. hello,


    ok, for geo tagging via map, i just tried to map an image group but just the first image in the group got the geo location set.

    i think it would be a very good feature if the mapping would run a loop of all images in the group.

    greetings
  10. Hi,

    thanks for the reminder, I just added it to this ticket:
    http://darktable.org/redmine/issues/8968
  11. I thought about this before but decided not to work in this direction since we would have to translate all the blog posts continuously, too - otherwise we end up with a mixed-language website... :)
  12. Ok, I will try to have a look at the documentation ;)
  13. This is fantastic.
    I used "GPS Essentials", on my S3, to log while I strolled around town taking random shots; walked about 2kms. The geotagging process in darktable works wonderfully and simply; all images placed correctly. It is strangely pleasing to see the exif data updated with a longitude and latitude.

    Thanks again for a great product.
  14. Hi,
    I shot many pictures on one location. From Google Earth I have got an KML and KMZ file with the GPS location.

    How can I apply the GPS location from a KML/KMZ file to all pictures?

    Thank you in advance.

    Mic
  15. I did it in the following way:
    1. Find in Google Earth your location
    2. Use Add Placemark and save it to KML file
    3. With http://geotag.sourceforge.net/ open one picture eg .IMGP0087.JPG and use the values from your KML file
    (KML file longitude,latitude,altitude).
    4. Save it and close geotag.
    6. You can check it with
    exiftool -GPSLongitude -GPSLatitude IMGP0087.JPG
    5. To apply all GPS information to all pictures use
    exiftool −overwrite_original_in_place -r -tagsFromFile IMGP0087.JPG -gps:all .
    the -r option recurses into the directory (.)

    However, this should be done before open the pictures in darktable, because later on darktable 1.1.1 does not show the updated GPS information.

    Further more it would be nice to get Geotag functionality in darktable and be able to select other pictures and copy the GPS information to them e.g. history stack.

    Would it be possible to modify the history stack so the user can choose what to apply to other pictures e.g. only GPS or only WB or both, ...?

    Thank you in advance.