The ExifTool geotagging feature adds GPS tags to images based on data from a GPS track log file. The GPS track log file is loaded, and linear interpolation is used to determine the GPS position at the time of the image, then the following tags are written to the image:
GPSLatitude GPSLongitude GPSAltitude GPSDateStamp GPSLatitudeRef GPSLongitudeRef GPSAltitudeRef GPSTimeStamp
Currently supported GPS track log file formats:
Geotagging is accomplished in ExifTool through the use of three special tags:
Geotag, Geosync and Geotime.
Note: When writing these tags, order is important. IfGeotimeis written, it must be done after bothGeotagandGeosync. Normally this is not a concern because the exiftool order of operations will copy all tags in batch processing after other directly assigned tags, but this should be kept in mind for cases where the value ofGeotimeis set directly from a date/time string.
The Geotag tag is used to define the GPS track log data. Setting
the value of this tag via the exiftool application activates the geotagging
feature. As an example, the following command line adds GPS tags to all images
in the "/Users/Phil/Pictures" directory based on GPS positions stored in the
track log file "track.log":
exiftool -geotag=track.log /Users/Phil/Pictures
As a convienience the exiftool application also provides a
-geotag option, so the following command is equivalent to the one
above:
exiftool -geotag track.log /Users/Phil/Pictures
Multiple GPS log files may be loaded simultaneously by using more than one
-geotag option (or by using wildcards in the filename argument
for the -geotag option, but note that here the filename may need
to be quoted -- see the examples below). This allows
batch processing of images spanning different tracks with a single command.
Deleting the Geotag tag causes the associated GPS tags to be
deleted from an image.
Programmers: You may write either a GPS log file name
or the GPS log data as the value for Geotag. If the value contains
a newline or a null byte it is assumed to be data, otherwise it is taken as a
file name.
The Geosync tag is needed only when the image timestamps are not
properly synchronized with GPS time, and must be set before Geotime
to be effective. The value written to the Geosync tag may take a
number of different forms, but the basic form is that of a simple time
difference which is added to Geotime before interpolating the GPS
position in the track log. This time difference may be of the form "SS",
"MM:SS", "HH:MM:SS" or "DD HH:MM:SS" (where SS=seconds, MM=minutes, HH=hours and
DD=days), and a leading "+" or "-" may be added for positive or negative
differences (negative if the camera clock was ahead of GPS time). Fractional
seconds are allowed (ie. "SS.ss").
For example, "-geosync=-1:20" specifies that synchronization
with GPS time is achieved by subtracting 1 minute and 20 seconds from the
Geotime value. See the Time Synchronization Tip
below for more details.
Note that a single decimal value is interpreted as
seconds when written to Geosync. This is different from of other
date/time shift values where a single value is normally taken as hours.
Camera clock drift correction:
A more advanced Geosync feature allows the GPS time and the
image time to be specified together, facilitating a time drift correction if
more than one synchronization point is provided. For this, the value written to
Geosync takes one of the following forms:
Format Notes FILE Both GPS and image timestamps are extracted from the specified file. ie) -geosync=image.jpgGPSTIME@FILE GPS time is taken from the Geosyncvalue and the image timestamp is extracted from the specified file. ie)-geosync="12:58:05@image.jpg"GPSTIME@IMGTIME Both GPS and image timestamps are taken from the Geosyncvalue. ie)-geosync="12:58:05@2010:01:02 12:25:26"
The values of GPSTIME and IMGTIME specified on the command line may contain a date, but it is not necessary.
Notes:
Geosync value is
written.The Geotime tag specifies the point in time for which the GPS
position is calculated (by interpolating between fixes in the GPS track log).
Unless a group is specified, exiftool writes the generated tags to the default
groups. If a value for Geotime is not given, it is taken from
DateTimeOriginal for each image (as if
"-Geotime<DateTimeOriginal" had been specified), but the value
may be copied from any other date/time tag or set directly from a date/time
string.
If the date/time tag does not include a timezone then one may be added (ie.
"-Geotime<${CreateDate}-05:00"), otherwise the local system time
is assumed.
By default, GPS tags are created in EXIF and the corresponding
XMP tags are updated only if they already exist. However, an EXIF or XMP group
name may be specified to force writing only to the specified location. For
example, writing XMP:Geotime or EXIF:Geotime will
write the generated GPS tags only to XMP or EXIF respectively. Note that when
written to XMP, the GPSLatitudeRef and GPSLongitudeRef
tags are not used, and the XMP GPSDateTime tag is written instead
of the separate EXIF GPSDateStamp and GPSTimeStamp
tags.
See the Examples section below for sample command lines illustrating various aspects of the geotagging feature.
Programmers: Note thatGeotimemust always be specified when geotagging via the API -- the default value ofDateTimeOriginalis implemented at the application level.
Geotag an image ("a.jpg") from position information in a GPS track log
("track.log"). Since the Geotime time is not specified, the value
of DateTimeOriginal is used. Local system time is assumed
unless DateTimeOriginal contains a timezone:
exiftool -geotag track.log a.jpg
Geotag all images in directory "dir" from the GPS positions in "track.log", for a camera clock that was running 25 seconds slower than the GPS clock:
exiftool -geotag track.log -geosync=+25 dir
Geotag an image with the GPS position for a specific time. (Note that the
Geotag tag must be assigned before Geotime for the GPS
data to be available when Geotime is set):
exiftool -geotag t.log -geotime="2009:04:02 13:41:12-05:00" a.jpg
Geotag all images in directory "dir" with XMP tags instead of EXIF tags,
based on the image CreateDate. (In this case, the order of the
arguments doesn't matter because tags with values copied from other tags are
always set after constant values):
exiftool -geotag log.gpx "-xmp:geotime<createdate" dir
Geotag images in "dir" using CreateDate with the specified
timezone. If CreateDate already contained a timezone, then the
timezone specified on the command line is ignored. (Note that in Windows,
double quotes (") must be used instead of single quotes
(') around the -geotime argument in the next 2
commands):
exiftool -geotag a.log '-geotime<${createdate}+01:00' dir
Geotag images for which the camera clock was set to UTC (+00:00), using
the time from DateTimeOriginal:
exiftool -geotag trk.gpx '-geotime<${DateTimeOriginal}+00:00' dir
Delete GPS tags which were added by the geotag feature. (Note that this does
not remove all GPS tags -- to do this instead use -gps:all=):
exiftool -geotag= a.jpg
Delete XMP GPS tags which were added by the geotag feature:
exiftool -xmp:geotag= a.jpg
Geotag an image with XMP tags, using the time from
DateTimeOriginal:
exiftool -xmp:geotag=track.log a.jpg
Combine multiple track logs and geotag an entire directory tree of images:
exiftool -geotag a.log -geotag b.log -r dir
Use wildcards to load multiple track files (the quotes are necessary for most operating systems to prevent filename expansion):
exiftool -geotag "logs/*.log" dir
Geotag from a sub-second date/time value with a sub-second time synchronization (only possible if the EXIF sub-second time stamps are available):
exiftool -Geotag a.log -Geosync=+13.42 "-Geotime<SubSecDateTimeOriginal" dir
Geotag images with a piecewise linear time drift correction using the GPS time synchronization from three already-geotagged images:
exiftool -geotag a.log -geosync=1.jpg -geosync=2.jpg -geosync=3.jpg dir
Geotagging may be configured via the following ExifTool options. These options have no command-line equivalents, but may be set using either the Options() function of the API or the %Image::ExifTool::UserDefined::Options hash of the config file. (See the sample config file for details about how to use the config file.)
Option Description Values Default GeoMaxIntSecs Maximum interpolation time in seconds for geotagging. Geotagging fails if the Geotime value lies between two fixes in the same track which are separated by a number of seconds greater than this. A floating point number 1800 GeoMaxExtSecs Maximum extrapolation time in seconds for geotagging. Geotagging fails if the Geotime value lies outside a GPS track by a number of seconds greater than this. A floating point number 1800 GeoMaxHDOP Maximum Horizontal (2D) Dilution Of Precision for geotagging. GPS fixes are ignored if the HDOP is greater than this. A floating point number, or undef to disable undef GeoMaxPDOP Maximum Position (3D) Dilution Of Precision for geotagging. GPS fixes are ignored if the PDOP is greater than this. A floating point number, or undef to disable undef GeoMinSats Minimum number of satellites for geotagging. GPS fixes are ignored if the number of acquired satellites is less than this. A positive integer, or undef to disable undef
1. "No track points found in GPS file"
If you see the above message, either exiftool does not yet support your track log file format, or your track log does not contain the necessary position/timestamp information. For instance, in KML files each Placemark must contain a TimeStamp. If you believe your track log contains the necessary information, please send me a sample file and I will add support for this format.
2. "0 image files updated"
If you see this message without any other warning messages, it is
likely that Geotime didn't get set properly.
Be sure that the necessary date/time tag exists in your image for copying toGeotime. Unless otherwise specified, the required tag isDateTimeOriginal. The following command may be used to list the names and values of all available date/time tags in an image:exiftool -s -time:all image.jpgEven if there is no metadata in the image you may be able to setGeotimefrom the filesystem modification date for the image (which will appear asFileModifyDatein the output of the above command). In this case you may also want to include the-Poption to preserve the original value ofFileModifyDate:exiftool -geotag track.gpx "-geotime<filemodifydate" -P image.jpgWithout the-Poption,FileModifyDateis set to the current date/time when the file is rewritten.
3. "Warning: Time is too far before track in File:Geotime (ValueConvInv)"
If you see a warning like this, you may have a time synchronization problem.
Try adding the-v2option to your command to output verbose information. You should see messages like this if the GPS track log was loaded successfully:Loaded 372 points from GPS track log file 'my_track.log' GPS track start: 2009:03:30 19:45:25 UTC GPS track end: 2009:04:03 11:16:04 UTCIf the number of points loaded and start/end times seem reasonable, then the problem is likely in the time synchronization. Also printed will be the UTC time for the image:Geotime value: 2009:04:03 10:57:01 UTCThe "Geotime value" must lie within 1/2 hour of a valid GPS fix in the track log for a position to be calculated. (1/2 hour is the default, but this can be configured via the geotagging Options.) The time calibration relies on proper synchronization between the GPS time and your camera's clock. If a timezone is not specified,Geotimeis converted to UTC using the local system timezone (as set by the shell's TZ environment variable). You should specify the timezone forGeotimeif your images were taken in a different timezone (see Examples above). If the camera clock was wrong, theGeosynctag may be used to apply a time correction, or the ExifTool time shift feature may be used to adjust the image times before geotagging -- see the Time Synchronization tip below for examples.
1. Time Synchronization
One way to accurately synchronize your images with GPS time is to take a picture of the time displayed on your GPS unit while you are out shooting. Then after you download your images you can use this image to synchronize the image timestamps for geotagging. This is done by using an image viewer to read the time from the GPS display in the image, and exiftool to extractDateTimeOriginalfrom the file. For example, if the time in the GPS display reads 19:32:21 UTC andDateTimeOriginalis 14:31:49, then for this image the camera clock was 32 seconds slow (assuming that the timezone of the camera clock was -05:00). There are two different ways to use this time synchronization to improve your geotagging accuracy:
A) Use theGeosynctag to specify the time difference while geotagging. Using this technique the existing image timestamps will not be corrected, but theGPSTimeStamptag created by the geotagging process will contain the correct GPS time:exiftool -geosync=+00:00:32 -geotag my_gps.log C:\Imagesor equivalently,exiftool -geosync=19:32:21Z@14:31:49-05:00 -geotag my_gps.log C:\Images(Note that this technique may also be used for a more advanced time drift correction. See the Geosync section above for details)
B) First fix the image timestamps by shifting them to synchronize with GPS time, then geotag using the corrected timestamps:exiftool -alldates+=00:00:32 C:\Images exiftool -geotag my_gps.log C:\ImagesBoth examples above assume that your track log file (my_gps.log) is in the current directory, that the images were downloaded to theC:\Imagesdirectory, and that the computer and camera clocks are in the same timezone.
The -p option may be used to output files in any number of formats.
This section gives examples for creating GPX and KML output files from a set of
geotagged images, or from a geotagged video file (see note below).
Note: The -ee option must be added to the
example commands below to extract all GPS fixes from a video file (such as the
M2TS videos from some Sony cameras), otherwise only the first GPS fix is
extracted.
The following print format file may be used to generate a GPX track log from one or more geotagged images:
#------------------------------------------------------------------------------ # File: gpx.fmt # # Description: Example ExifTool print format file for generating GPX track log # # Usage: exiftool -p gpx.fmt -d %Y-%m-%dT%H:%M:%SZ FILE [...] > out.gpx # # Revisions: 2010/02/05 - P. Harvey created # # Notes: 1) All input files must contain GPSLatitude and GPSLongitude. # 2) The -fileOrder option may be used to control the order of the # generated track points. #------------------------------------------------------------------------------ #[HEAD]<?xml version="1.0" encoding="utf-8"?> #[HEAD]<gpx version="1.0" #[HEAD] creator="ExifTool $ExifToolVersion" #[HEAD] xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" #[HEAD] xmlns="http://www.topografix.com/GPX/1/0" #[HEAD] xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd"> #[HEAD]<trk> #[HEAD]<number>1</number> #[HEAD]<trkseg> #[BODY]<trkpt lat="$gpslatitude#" lon="$gpslongitude#"> #[BODY] <ele>$gpsaltitude#</ele> #[BODY] <time>$gpsdatetime</time> #[BODY]</trkpt> #[TAIL]</trkseg> #[TAIL]</trk> #[TAIL]</gpx>
This example assumes that the GPSLatitude,
GPSLongitude, GPSAltitude and GPSDateTime
tags are all available in each processed FILE. Warnings will be
generated for missing tags. The output GPX format will invalid if any
GPSLatitude or GPSLongitude tags are missing, but will
be OK for missing GPSAltitude or GPSDateTime tags.
Note that the order of track points in the output GPX file will be the same
as the order of processing the input files, which may not be chronological
depending on how the files are named. The -fileOrder option may be
used to force processing of files in a particular order. For example, the
following command processes files in order of increasing GPSDateTime:
exiftool -fileOrder gpsdatetime -p gpx.fmt -d %Y-%m-%dT%H:%M:%SZ /Users/Phil/Pictures > out.gpx
Since no directory was specified for gpx.fmt, this file must
exist in the current directory when the above command is executed. (If the
gpx.fmt file can't be found then the -p argument is
interpreted as a string instead of a file name, and the text
"gpx.fmt" is sent to the output, which isn't what we want.)
The -if option may be added to ensure that only files containing
GPS information are processed. For example, the following command creates
"out.gpx" in the current directory from all pictures containing
GPSDateTime information in directory "pics" and its
sub-directories:
exiftool -r -if '$gpsdatetime' -fileOrder gpsdatetime -p gpx.fmt -d %Y-%m-%dT%H:%M:%SZ pics > out.gpx
Note: In Windows, double quotes (") must be used instead of
single quotes (') around the -if argument above.
The full exiftool distribution contains this sample format file ("gpx.fmt") as well as a sample which creates GPX waypoints with pictures ("gpx_wpt.fmt").
Below is an example of a print format file which generates a Google Earth KML file from a collection of geotagged images:
#------------------------------------------------------------------------------ # File: kml.fmt # # Description: Example ExifTool print format file for generating a # Google Earth KML file from a collection of geotagged images # # Usage: exiftool -p kml.fmt FILE [...] > out.kml # # Revisions: 2010/02/05 - P. Harvey created # # Notes: 1) All input files must contain GPSLatitude and GPSLongitude. # 2) The -fileOrder option may be used to control the order of the # generated placemarks. #------------------------------------------------------------------------------ #[HEAD]<?xml version="1.0" encoding="UTF-8"?> #[HEAD]<kml xmlns="http://earth.google.com/kml/2.0"> #[HEAD] <Document> #[HEAD] <name>My Photos</name> #[HEAD] <open>1</open> #[HEAD] <Style id="Photo"> #[HEAD] <geomScale>.75</geomScale> #[HEAD] <IconStyle> #[HEAD] <color>ffffffff</color> #[HEAD] <Icon> #[HEAD] <href>root://icons/palette-4.png</href> #[HEAD] <x>192</x> #[HEAD] <y>96</y> #[HEAD] <w>32</w> #[HEAD] <h>32</h> #[HEAD] </Icon> #[HEAD] </IconStyle> #[HEAD] </Style> #[HEAD] <Style id="View"> #[HEAD] <IconStyle> #[HEAD] <color>ffffffff</color> #[HEAD] <Icon> #[HEAD] <href>root://icons/palette-3.png</href> #[HEAD] <x>160</x> #[HEAD] <y>128</y> #[HEAD] <w>32</w> #[HEAD] <h>32</h> #[HEAD] </Icon> #[HEAD] </IconStyle> #[HEAD] </Style> #[HEAD] <Folder> #[HEAD] <name>Waypoints</name> #[HEAD] <open>0</open> #[BODY] <Placemark> #[BODY] <description><![CDATA[<br/><table><tr><td> #[BODY] <img src='$directory/$filename' #[BODY] width='$imagewidth' height='$imageheight'> #[BODY] </td></tr></table>]]></description> #[BODY] <Snippet/> #[BODY] <name>$filename</name> #[BODY] <styleUrl>#Photo</styleUrl> #[BODY] <Point> #[BODY] <altitudeMode>clampedToGround</altitudeMode> #[BODY] <coordinates>$gpslongitude#,$gpslatitude#,0</coordinates> #[BODY] </Point> #[BODY] </Placemark> #[TAIL] </Folder> #[TAIL] </Document> #[TAIL]</kml>
[These example -p files are included
in the full ExifTool distribution.]