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 two special tags:
Geotag
and Geotime
.
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. 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.
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 to a date/time string.
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: You may write either a GPS log file name or the GPS log data as the value forGeotag
. If the value contains a newline it is assumed to be data, otherwise it is taken as a file name. Note thatGeotime
must always be specified when geotagging via the API -- the default value ofDateTimeOriginal
is implemented only by the exiftool application.
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 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:
exiftool -geotag a.log '-geotime<${createdate}+01:00' dir
Delete GPS tags which were added by the geotag feature:
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
If you see the following message, it is likely that exiftool does not yet support your track log file format:
No track points found in GPS file
In this case, please send me a sample file and I will add support for this format.
If you see this message without any other warning messages, it is likely that
Geotime
didn't get set properly:
0 image files updated 1 image files unchanged
Be sure that the necessary date/time tag exists in your image if copying this
value to the Geotime
tag (this will be
DateTimeOriginal
if not specified otherwise). Without this date,
the image will not be geotagged.
If you see a warning like this, you may have a time synchronization problem:
Warning: Time is too far before track in File:Geotime (ValueConvInv)
Try adding the -v2
option 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 UTC
If 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 UTC
The "Geotime value" must lie within 1/2 hour of a valid GPS fix in the track
log for a position to be calculated. The time calibration relies on proper
synchronization between the GPS time and your camera's clock. If a timezone is
not specified, Geotime
is converted to UTC using the local system
timezone. You should specify the timezone for Geotime
if your
images were taken in a different timezone (see examples above). If the camera
clock was wrong, the ExifTool time shift feature may be used to adjust the image
times.
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 look at this image to get the GPS time and use ExifTool to extract DateTimeOriginal. Say, for example, that the GPS clock reads 19:32:21, DateTimeOriginal is 14:31:49, and your timezone is -05:00. In this case, your camera clock is 32 seconds slow, so you would synchronize your pictures using the following exiftool command:
exiftool -alldates+=00:00:32 C:\Images
(assuming that you downloaded the images to the C:\Images
directory). The geotagging will be more accurate after synchronizing the image
times like this.