This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 2.5 Switzerland License.

A simple example using gpsPhoto.pl in batch mode to geo-tag your images.

In the following I going to show one possible way to geo-tag images in batch processing mode. To add some salt the example images were taken at a time when no GPS-data was recorded. Instead the photographer has been at the exact same location the day before and is therefore using already existing GPS-Data. This circumstance gives us the opportunity to take a closer look at the interdependence of the two most important parameters in gpsPhoto.pl:

• --timeoffset
• --maxtimediff

--timeoffset is a mandatroy parameter and describes the difference of time in seconds between the camera and the GPS-device. A positive value means that the time of the camera is behind the time of the GPS. A negative value reflects that the camera is ahead of the GPS.
Changes in daylight saving time (DST) is often the cause of discrepancies. As a starting point you may include a 1 hour difference (plus or minus) like this: --timeoffset 3600.
In case your GPS stores date time using the UTC (Universal Time Coordinated) according to ISO 8601 then you will have to take into account the difference to your local time. UTC time is also known as 'Zulu' time, since 'Zulu' is the NATO phonetic alphabet word for 'Z'.
Most GPS units store date/time in UTC format by default, like this: 2009-01-22T12:45:40Z

--maxtimediff describes the maximum time difference in seconds between the image Exif:DateTimeOriginal and the corresponding timestamp recorded by the GPS in the GPS-Data.

The goal is to line up the images relative to time of existing GPS-data of the same location, then read and insert exisiting GPS-data into the images as a preparation for further processing with gpsPhoto.pl.
As the the images in this sample produce a panoramic image the values of the GPS-coordinates are equal, hence a simpler copy command with ExifTool by Phil Harvey would have produced pretty much the same result.

The procedure described here applies, for example, if we had images of a hike we have taken some time ago or in the future in conjunction with available GPS data in gpx-Format.

In order to match your images with exact geodetic information one would need to use a low recording interval of track-points and most important camera and GPS should be synchronized.
The easiest way to synchronize the GPS with your camera is to simply take a shot of your GPS displaying its date and time. Back home you simply calculate the difference between the time your GPS is showing on the image with the Exif:DateTimeOriginal of that same image. This value is then used for the --timeoffset parameter and the --maxtimediff parameter should be half the value of your tracking interval.

In order to obtain satisfying results when inserting GPS-data into images, a basic understanding of these two paramters is essential.

prerequisits:

• - a running environment for ExifTool and gpsPhoto.pl (gpsPhoto and ExifTool are accessible via the system path)
• - some TIFF-image files with Exif-data for Date & Time the image was taken
• - Images are located in the folder 'c:\tmp\images\converted\'
• - raw GPS-data in gpx-Format
• - the corresponding GPS-data file is in 'c:\tmp\gps\'
• - commands are executed from within a DOS-Window and the images folder 'c:\tmp\images\converted\'

In case you're not sure if gpsPhoto and ExifTool are accessible via the system path, open a DOS-Box (start / run / 'cmd') at the DOS-Prompt type: set
Somewhere in the path-statement you should find at least these two variables 'C:\Perl\bin\;' and 'C:\WINDOWS;'
(if not, set it or provide the path to 'gpsphoto.pl' in the command-lines used below.

create a list of your TIFF-images with this command:

dir *.tif /b > filelist.txt

gpsPhoto.pl can also add GPS data to files in .jpg and .psd format.
In case you need to quickly modify the Exif tag 'DateTimeOriginal' in a PSD file you may consider using the great tool ExifToolGUI (which is no longer maintained).

The list sould look similar to this one:

SDIM3215.tif
SDIM3216.tif
SDIM3217.tif
SDIM3218.tif
SDIM3219.tif
SDIM3220.tif
SDIM3221.tif
SDIM3222.tif
SDIM3223.tif
SDIM3224.tif
SDIM3225.tif
SDIM3226.tif

In case you wish to include the complete path to your images use the command below:

dir *.tif /s/b > filelist.txt

This allows to omit the paths statements in the command-line.

For further processing on your own, you would need to select one of your own images and record the Date & Time the was taken and also you would need to know which GPS-data file (.gpx) corresponds to your images and edit the command-lines used here.

First apply the calculations as outlined in this example (see below) and then invoke the following command:

gpsphoto.pl -I filelist.txt --gpsfile c:\tmp\gps\20080822-CH-ZRH.gpx --overwrite-geotagged --timeoffset 67800 --maxtimediff 151 --dry-run

The calculated timeoffset is set 67800 seconds that equals to a time difference of 18 hrs 49.9 Minutes between the camera data when the shot was taken and the GPS unit.
The math goes as follows:

18.83333... hours / 67800 : 3600 (= 1 hour) = 18.8333...

0.83333... hours / 0.83333 x 60 (= 1 Minute) = 49.9998 Minutes

The maxtimediff is set to 151 seconds because the GPS-unit in this example is instructed to record a trackpoint every 5 Minutes (300 seconds).
So the maximum time between 1 shot and a trackpoint is equal or less than 150 seconds. But we put 151 in order not to miss an the exact match of 150.

Take a close look at results processed by gpsPhoto.pl below.
From these first results we can draw some conclusions and then apply necessary fine-tunning.

Conclusions:

• - during the time when taking the shots there was no GPS-data recorded
• - another set of GPS-data has been applied to these shots, knowing that GPS-data existed for that specific location
• - seemingly there is only one track point for that period of time as the results shows only one targettime 10:34:20
• - From these two facts we can calculate the large difference between the moment of taking the shots and the recording time of the GPS-data (--timeoffset 67800)
• - In this cirumstance the parameter --maxtimediff apparently was calculated off the last image SDIM3226.tif as it shows the lowest value for --timediff
• - Some images processed here were processed before as gpsPhoto.pl is reading from the file (get geotag from meta info)

C:\tmp\images\converted\SDIM3215.tif, 2008-08-14T15:41:16Z, timediff=184, get geotag from meta info.
Lat 47.3124833333333, Lon 8.55413333333333 - Bearing: 0 - Altitude: 431m
C:\tmp\images\converted\SDIM3216.tif, 2008-08-14T15:41:42Z, timediff=158, get geotag from meta info.
Lat 47.3126611111111, Lon 8.55386388888889 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3217.tif, 2008-08-14T15:42:14Z, timediff=126 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3218.tif, 2008-08-14T15:42:32Z, timediff=108 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3219.tif, 2008-08-14T15:43:57Z, timediff=23 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3220.tif, 2008-08-14T15:43:57Z, timediff=23 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3221.tif, 2008-08-14T15:43:58Z, timediff=22 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3222.tif, 2008-08-14T15:44:10Z, timediff=10 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3223.tif, 2008-08-14T15:44:11Z, timediff=9 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3224.tif, 2008-08-14T15:44:11Z, timediff=9 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3225.tif, 2008-08-14T15:44:24Z, timediff=4 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3226.tif, 2008-08-14T15:44:25Z, timediff=5 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m 

fine-tunning:
There are two options for the fine-tunning as there are two paramters we can tweak:

• - The easiest way is to simply raise the -- maxtimediff to 185 seconds
• - The correct way would be to to calculate the --maxtimediff off an image that was taken just about in the middle of the shooting period

So we do the math again for the image SDIM3221.tif. This shot was taken on 2008-08-14 at 15:43:58 and corresponds to the Exif-Value 'DateTimeOriginal' in the image. Basically we calculate time in seconds that passed between 2008-08-14/15:43:58 and 2008-08-15/10:34:20. This period sums up to 67824 seconds. In addition we add the parameter --dry-run that allows us to see what would happen without gpsPhoto.pl writing to the image-files.

gpsphoto.pl -I filelist.txt --gpsfile c:\tmp\gps\20080822-CH-ZRH.gpx --overwrite-geotagged --timeoffset 67824 --maxtimediff 151 --dry-run

C:\tmp\images\converted\SDIM3215.tif, 2008-08-14T15:41:16Z, timediff=160, get geotag from meta info.
Lat 47.3124833333333, Lon 8.55413333333333 - Bearing: 0 - Altitude: 431m
C:\tmp\images\converted\SDIM3216.tif, 2008-08-14T15:41:42Z, timediff=134 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3217.tif, 2008-08-14T15:42:14Z, timediff=102 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3218.tif, 2008-08-14T15:42:32Z, timediff=84 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3219.tif, 2008-08-14T15:43:57Z, timediff=1 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3220.tif, 2008-08-14T15:43:57Z, timediff=1 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3221.tif, 2008-08-14T15:43:58Z, timediff=2 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3222.tif, 2008-08-14T15:44:10Z, timediff=14 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3223.tif, 2008-08-14T15:44:11Z, timediff=15 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3224.tif, 2008-08-14T15:44:11Z, timediff=15 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3225.tif, 2008-08-14T15:44:24Z, timediff=28 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3226.tif, 2008-08-14T15:44:25Z, timediff=29 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m

The result clearly shows a slight time-shift (24 seconds) upwards.
Apparently the selection of the image SDIM3221.tif was wrong as there is still one image out of range. So we sould shift the parameter --maxtimediff upwards again. In the first result this image was out of range by 184 seconds and for the second run we only applied a correction 24 seconds.
The correct correction for the parameter --maxtimediff would have been 184 - 150 = 34 - 24 = 10 seconds.

Lets try with the corrected parameter:

gpsphoto.pl -I filelist.txt --gpsfile c:\tmp\gps\20080822-CH-ZRH.gpx --overwrite-geotagged --timeoffset 67834 --maxtimediff 151 --dry-run

C:\tmp\images\converted\SDIM3215.tif, 2008-08-14T15:41:16Z, timediff=150 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3216.tif, 2008-08-14T15:41:42Z, timediff=124 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3217.tif, 2008-08-14T15:42:14Z, timediff=92 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3218.tif, 2008-08-14T15:42:32Z, timediff=74 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3219.tif, 2008-08-14T15:43:57Z, timediff=11 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3220.tif, 2008-08-14T15:43:57Z, timediff=11 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3221.tif, 2008-08-14T15:43:58Z, timediff=12 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3222.tif, 2008-08-14T15:44:10Z, timediff=24 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3223.tif, 2008-08-14T15:44:11Z, timediff=25 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3224.tif, 2008-08-14T15:44:11Z, timediff=25 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3225.tif, 2008-08-14T15:44:24Z, timediff=38 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m
C:\tmp\images\converted\SDIM3226.tif, 2008-08-14T15:44:25Z, timediff=39 to 10:34:20
Lat 47.3126610, Lon 8.5538628 - Bearing: 0 - Altitude: 479m

Seems to be allright for our purpose. Now that we are happy with what we had anticipated, this command can now fire at your image files. The effect is that each image will now have its proper geo-tag.

The on-line listing with a detailed explanation for all options gpsPhoto provides can be found on the project page at SourceForge:
Syntax and options for gpsPhoto.pl
Visit the site of carto:net to obtain and use gpsPhoto.

I hope this little tutorial and excursion helped you in getting used to using gpsPhoto.pl.
gpsPhoto.pl is still the best application for effective geo-tagging and batch-processing image data.

For all those who made it this far I have the final result ready. Geodetic Annotation is one step in a rather long workflow till panoramics like shown here are ready. Thank you for your attention - enjoy.
View the final result of the sample images.

Credits:
Many thanks to the developers of gpsPhoto, Andreas Neumann, Peter Sykora and Uwe Girlich enhancing and maintaining the gpsPhoto-Project on Source Forge.

This document was created by Hans Loepfe, HALO-Photographs.com, August 21st. 2008.
Last update on January, 21st., 2010.

For further inquiries feel free to contact me using the contact form: Contact & Anfragen