Provided by: gpscorrelate_2.3-0.1build1_amd64 
NAME
gpscorrelate - correlates digital images with GPS data filling EXIF fields
SYNOPSIS
gpscorrelate [{-g file.gpx} | {[-l | --latlong latitude,longitude[,elevation] ]}] [-z |
--timeadd +/-HH[:MM]] [--no-photo-tz] [-O | --photooffset seconds] [-i | --no-interpolation]
[-v | --verbose] [-d | --datum datum] [-n | --no-write] [-R | --replace] [-m |
--max-dist time] [-t | --ignore-tracksegs] [--heading] [-B | --max-heading degrees] [-b |
--direction degrees] [-M | --no-mtime] [--degmins] image.jpg...
gpscorrelate {-s | --show | -o | --machine} image.jpg...
gpscorrelate {-x | --show-gpx} [-z | --timeadd +/-HH[:MM]] [--no-photo-tz] [-O | --photooffset seconds]
image.jpg...
gpscorrelate {-r | --remove} [-M | --no-mtime] image.jpg...
gpscorrelate {-f | --fix-datestamps} {-z | --timeadd +/-HH[:MM]} image.jpg...
gpscorrelate -V | --version | -h | --help
DESCRIPTION
This manual page documents the gpscorrelate command. There is extended documentation available in HTML
format; see below.
gpscorrelate is a program that acts on digital images in JPEG format, filling in the EXIF (Exchangeable
Image File Format) fields related to GPS (Global Positioning System) information. Source for the GPS data
is a GPX (GPS Exchange Format) file, which records GPS location information in an XML-based format. The
act of filling those fields is referred to as correlation.
If GPS data are available at the precise moment the image was taken (with a 1-second granularity) the GPS
data are stored unmodified in EXIF fields. If they are not, linear interpolation of GPS data available at
moments before and after the image was taken can be used. If the image contains sub-second time
resolution, it is used to obtain a more accurate estimate of the position between the two points. Linear
interpolation gives good results when points are close together, but if they are several kilometres apart
(such as on an infrequently-sampled airplane track), it will introduce some error versus the great circle
route an airplane normally flies. A measure of the approximate accuracy of the GPS location reading
(based on the number of digits recorded in the track point) is preserved when written into the image
through the denominator of rational value fields. A GPSDOP tag is also written for exact point matches
when satellite HDOP information is available, providing a more dependable estimate of location accuracy.
The interpolation algorithm assumes that time values in GPX files are strictly increasing, which is
normally the case. If a GPX file is found to violate this assumption, the message Warning: track points
are not ordered by time is written so stderr along with the first backwards-going time value. Any
location values written to images using such a file may not be using the best GPS coordinate points
available if the images were taken around the time of the time incongruity. No warning is given if time
between track segments goes backwards, which would only affect correlations when --ignore-tracksegs is
used. The --max-dist option can be used to place a limit on how large a time gap is accepted, which can
limit the effect if this occurs.
OPTIONS
These programs follow the usual GNU command line syntax, with long options starting with two dashes
(`-'). A summary of options is included below.
-g, --gps file.gpx
Correlate images using the specified GPX file containing GPS track points. This option can be given
many times to specify multiple GPX files. For each photo being correlated, the first file containing
a track covering the time the photo was taken will be the one used. All <trk> segments in each file
are used.
-l, --latlong latitude,longitude[,elevation]
Provide a specific geographic coordinate to use for all images instead correlating along a path in a
GPX file. The format must be of the general form latitude,longitude,elevation where latitude and
longitude must each be in either decimal form, such as -123.45678 or in degrees/minutes/seconds form,
such as -123°45'67.8" or -123d45m67s. Providing an elevation is optional. Each component can be
separated by commas, spaces or tabs.
Note that this option has a known limitation in that it does not honour the locale's decimal place
character in locales that use other than ".".
-s, --show
Only show the GPS data already in the given image's EXIF tags instead of correlating them. The time
shown comes directly from the image without adjustments.
-x, --show-gpx
Only show the GPS data in the given images in GPX format. Note that the points are written in the
order in which the images are found on the command-line, so be sure to give them in the order in
which they were photographed. The -z/--timeadd and -O/--photooffset options are honoured just as in
correlation to determine the correct time zone of the images. Images that can't be read or aren't GPS
tagged are ignored. If the times of the photos given on the command-line are not strictly increasing,
the message Warning: image files are not ordered by time. is written to stderr.
-o, --machine
Only show the GPS data of the given images in a machine-readable CSV format. The time shown comes
directly from the image without adjustments. Images without GPS tags are ignored. The fields output
are file name, date and time, latitude, longitude, elevation, where the first value is the filename,
as passed, the second is the timestamp, and the last three are floating point values with an optional
leading plus or minus.
-r, --remove
Remove all GPS EXIF data from the given images. Note that this only removes the GPS tags that the
program could add; it does not delete all possible GPS EXIF tags. All other tags are left alone.
-z, --timeadd +/-HH[:MM]
Time to add to GPS points to make them match the timestamps of the images. GPS timestamps are in UTC;
image timestamps are generally in local time. Enter the timezone used when taking the images; e.g.,
+8 for Perth, Western Australia or -2:30 for St. John's, Newfoundland. This defaults to the time zone
embedded in the image, or if that is not available (or when --no-photo-tz is given), the UTC offset
of the local time zone as of the time of the first image processed (versions before 1.7 defaulted to
00:00).
--no-photo-tz
Ignore any OffsetTimeOriginal EXIF tags in photos that specify the time zone in which the photo was
taken. If the tag is wrong, such as if the user forgot to update the time zone manually when
travelling, then this will prevent it from being used. If this option is given, then gpscorrelate
reverts to using automatic time zone detection for the photo, or a manually-specified one (if
--timeadd is given).
-O, --photooffset seconds
Time in seconds (fractional seconds are allowed) to add to the photo timestamp to make it match the
GPS timestamp. To determine the number of seconds needed, just create a photograph of your GPS device
showing the current time and compare it with the timestamp of your photo file. The EXIF time tags in
the image are not modified based on this value.
-i, --no-interpolation
Disable linear interpolation between points. With this flag, the nearest exact point (within
--max-dist) is used. Without this flag, photos taken between the time of two recorded GPS coordinates
are correlated based on linear interpolation between those two points.
-v, --verbose
Show slightly more information during the image correlation process, such as the GPS data selected
for each image.
-d, --datum datum
Specify GPS measurement datum. If not set, WGS-84 is used (TOKYO is another possibility). However,
GPX is not supposed to store anything but WGS-84, so this should only ever be needed with the
--latlong option.
-n, --no-write
Do not write the correlated EXIF data back into the image. Useful with --verbose to see what would
happen during image correlation.
-R, --replace
Overwrite any existing GPS tags in the file. Without this option, any file that already contains GPS
tags will be skipped.
-m, --max-dist time
Maximum time in seconds from the photo time which a logged GPS point can refer and still be used for
correlation. This defaults to 0, which means to disable this check. Only one of the two points need
be within this range for correlation to take place.
If a clear view of sufficient GPS satellites is lost while recording a track, then there may be
location gaps in the GPX file. If the accuracy of the recorded location is paramount and you would
rather not correlate a position at all for a photo if the available GPS coordinates were recorded too
long ago in the past or too far into the future (relative to when the photo was taken), then set this
to a nonzero value.
This option will also prevent recording heading and direction under the same circumstances (see
--max-heading for a discussion of when this may be needed).
-t, --ignore-tracksegs
Interpolate between track segments, too. Generally, track segments show multiple sessions of GPS
logging; between them is generally when the GPS was not logging. Since interpolation honours the
--max-dist flag, even track segments with wide time gaps can safely be used if both flags are set.
Without this flag, photos taken within the time gap between two <trkseg> tracks in the GPX file are
not correlated.
--heading
Write an EXIF tag showing the direction of movement at the time of image capture. This is only
possible if the direction is written in an appropriate tag within a <trkpt> entry in the GPX file.
Supported tags are course (from GPX 1.0), extensions/TrackPointExtension/course (a Garmin®
TrackPointExtension), and extensions/compass (written by OSMTracker).
gpscorrelate treats each of these tags as holding the true direction of movement, but they aren't
very well defined and might not hold exactly what's expected. For example, a phone might store the
direction it's facing rather than the direction of movement, or the direction might be the magnetic
heading instead of true heading. Or, a device might estimate the heading from GPS movement which will
be inaccurate at slow speeds. Use your knowledge of the recording application to determine how much
faith you can place in the resulting tags.
If this is used with --latlong instead of with --gps, then a fixed heading of 0 is written (this is
subject to change in the future).
-B, --max-heading degrees
Don't write the tags for --heading and --direction for images where the heading has changed by more
than the specified number of degrees between the GPX points being used. This prevents writing a value
that is likely to be inaccurate because the image was taken during a sharp turn. This is off by
default.
This option won't prevent writing an incorrect heading or direction in the case where GPS points are
sparser than the time it takes the recording vehicle to make a nearly 360° turn. For example, if the
vehicle takes 8 seconds to turn completely around but GPS tags are written every 10 seconds, then the
two points written at either end of the turn could have headings that are very close (within
--max-heading) yet a picture taken in the middle of the turn, 4 seconds after the first tag, would
have an interpolated heading that is around 180° off the correct value. Prevent this kind of bad
value from being written by setting a --max-dist that is much less than the time it takes to turn
around, such as 4 in this example.
-b, --direction degrees
write an EXIF tag showing the direction the camera was pointing when the image was taken. The degrees
argument gives the offset between the direction of travel (the value that would be written if
--heading were given) and the camera direction. For example, if the camera is mounted pointing out
the right side window of a car then this would be specified as --direction 90. If --heading is also
given, then the two tags will always be this number of degrees apart. If accuracy is important, use
the --max-heading and --max-dist options to limit writing these tags to times when there is a good
fix on the position and not during a sharp turn. Since this option applies along the entire track,
it's only generally useful when the camera is fixed in the vehicle during the trip.
This may be used with --latlong in which case the argument is used as the camera direction without
alteration.
-M, --no-mtime
Do not change the last modification time of changed files.
-f, --fix-datestamps
Fix broken GPS datestamps written with gpscorrelate versions < 1.5.2 by replacing them with the
photo's time stamp. Prior to 1.5.2, two bugs wrote the wrong value for the GPSDateStamp and
GPSTimeStamp tags. This option will check each supplied filename for the problem and correct it. Use
with --no-write to prevent writing these changes (useful for checking for the issue). This option
also implies --no-mtime. You will also need to use --timeadd to specify the difference between
localtime and UTC time for the supplied photos.
--degmins
Write location as DD MM.MM (instead of the more accurate DD MM SS.SS) as was the default in
gpscorrelate versions < 1.5.3. There is no good reason to use this option unless some broken program
expects this style.
-h, --help
Only show a summary of options.
-V, --version
Only print the gpscorrelate version number and copyright information.
EXAMPLES
Correlate all photos in a directory taken in western Europe in the summer (i.e., UTC-2):
gpscorrelate -g Test.gpx -z 2 *.jpg
Correlate all photos in a directory taken in Italy, switching to UTC-2 or UTC-1 depending on the daylight
savings time in effect when the first picture in the list was taken:
env TZ=Europe/Rome gpscorrelate -g Test.gpx *.jpg
Correlate all photos in a directory from a track spread out over two different track files and taken in
the computer's current time zone, interpolating between segments and between files while ignoring photos
taken too far away from a recorded point, without changing the file time stamp of the files, while
showing details of the process:
gpscorrelate -g track1.gpx -g track2.gpx -m 120 -t -M -v *.jpg
Correlate images taken from a dashcam, adding direction tags from the GPX file:
gpscorrelate --heading --max-heading 90 --direction 0 -g Test.gpx *.jpg
Correlate a set of photos taken with a camera aimed straight out of the right-hand passenger side window
of a car (90° from straight ahead), using a GPX file containing direction tags, skipping direction
tagging during fast turns and all tags when a GPS lock is lost for more than 6 seconds (to avoid writing
inaccurate tags):
gpscorrelate -g car_trip.gpx --heading --max-heading 45 --direction 90 --max-dist 6 --ignore-tracksegs
*.jpg
Correlate a photo taken from a camera with a fast clock (i.e., the clock was 77.5 seconds ahead of GPS
time) and with incorrectly-specified time zone tags:
gpscorrelate -g Test.gpx -O -77.5 --no-photo-tz photo.jpg
Show existing GPS tags in a photo:
gpscorrelate --show photo.jpg
Show existing GPS tags in a photo and output in CSV format:
gpscorrelate --show --machine photo.jpg
Create a GPX track from a set of images taken in the UK in winter that are already GPS tagged (e.g., as
might come from a cell phone camera), which can be used to correlate other photos taken on another nearby
camera:
gpscorrelate --show-gpx -z 0 IMG*.JPG
Remove GPS tags from photos:
gpscorrelate --remove *.jpg
Add a GPS location tag to a photo taken to the southeast at Ulmer Münster:
gpscorrelate -l 48.398620,9.991417,522 --direction 135 -z 2 ulm.jpg
EXIT STATUS
gpscorrelate returns 0 in case of success, 1 in case of major error (such as a read or write error) and 2
in case of minor error (such as the given GPS track not covering the time of an image).
SEE ALSO
gpsd(1), gpsbabel(1), gpxlogger(1), cgpxlogger(1).
The documentation of gpscorrelate in HTML format is available on the filesystem at
/usr/share/doc/gpscorrelate.
LICENSE
This manual page was initially written by Stefano Zacchiroli <zack@debian.org> for the Debian(TM) system.
It was extended by Till Maas <opensource@till.name> and Dan Fandrich <dan@coneharvesters.com>. Permission
is granted to copy, distribute and/or modify this document under the terms of the GNU General Public
License, Version 2 or any later version published by the Free Software Foundation.
AUTHOR
Stefano Zacchiroli
Author.
COPYRIGHT
Copyright © 2006-2025 Stefano Zacchiroli <zack@debian.org>, Till Maas, Dan Fandrich
gpscorrelate 2.3 13 Feb 2025 GPSCORRELATE(1)