Implementation
Examples
Options
Troubleshooting
Tips

# Geotagging with ExifTool

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:

- GPX
- NMEA (RMC, GGA, GLL and GSA sentences)
- KML
- IGC (glider format)
- Garmin XML and TCX
- Magellan eXplorist PMGNTRK

### Implementation

Geotagging is accomplished in ExifTool through the use of three special tags: `Geotag`, `Geosync` and `Geotime`.

> Note: When writing these tags, order is important. If `Geotime` is written, it must be done after both `Geotag` and `Geosync`. 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 of `Geotime` is set directly from a date/time string.

#### Geotag

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 last example 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.

#### Geosync

The `Geosync` tag is needed only when the image timestamps are not properly synchronized with GPS time. The `Geosync` value is added to `Geotime` before interpolating the GPS position in the track log. `Geosync` values should be in the format "SS", "MM:SS", "HH:MM:SS" or "DD HH:MM:SS" (where SS=seconds, MM=minutes, HH=hours and DD=days). A leading "+" or "-" may be added for positive or negative differences (negative if the camera clock was ahead of GPS time), and 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.

#### Geotime

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 that `Geotime` must always be specified when geotagging via the API -- the default value of `DateTimeOriginal` is implemented at the application level.

### Examples

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:

    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

### Options

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

### Troubleshooting

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 to `Geotime`. Unless otherwise specified, the required tag is `DateTimeOriginal`. 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.jpg

> Even if there is no metadata in the image you may be able to set `Geotime` from the filesystem modification date for the image (which will appear as `FileModifyDate` in the output of the above command). In this case you may also want to include the `-P` option to preserve the original value of `FileModifyDate`:

>     exiftool -geotag track.gpx "-geotime<filemodifydate" -P image.jpg

> Without the `-P` option, `FileModifyDate` is 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 `-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. (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, `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 `Geosync` tag 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.

### Tips

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 extract `DateTimeOriginal` from the file. For example, if the time in the GPS display reads 19:32:21 UTC and `DateTimeOriginal` is 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 the `Geosync` tag to specify the time difference while geotagging. Using this technique the existing image timestamps will not be corrected, but the `GPSTimeStamp` tag created by the geotagging process will contain the correct GPS time:

>     exiftool -geosync=+00:00:32 -geotag my_gps.log C:\Images

> or 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:\Images

> Both examples above assume that your track log file (`my_gps.log`) is in the current directory, that the images were downloaded to the `C:\Images` directory, and that the computer and camera clocks are in the same timezone.

Last revised Oct. 3, 2009

<-- Back to ExifTool home page