table of contents
GPSCORRELATE(1) | gpscorrelate 2.1 | GPSCORRELATE(1) |
NAME¶
gpscorrelate - correlates digital images with GPS data filling EXIF fields
SYNOPSIS¶
gpscorrelate [-z | --timeadd +/-HH[:MM]] [-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] [-g file.gpx | [-l | --latlong] latitude,longitude[,elevation]] image.jpg...
gpscorrelate -s | --show | -x | --show-gpx | -o | --machine 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. Linear interpolation gives good results when points are close together, but if they are several kilometres apart on an airplane route, it will introduce some error versus the great circle route an airplane flies. A measure of the approximate accuracy of the GPS location reading is preserved when written into the image.
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
-l, --latlong latitude,longitude[,elevation]
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
-x, --show-gpx
-o, --machine
-r, --remove
-z, --timeadd +/-HH[:MM]
-O, --photooffset seconds
-i, --no-interpolation
-v, --verbose
-d, --datum datum
-n, --no-write
-R, --replace
-m, --max-dist time
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
--heading
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
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
This may be used with --latlong in which case the argument is used as the camera direction without alteration.
-M, --no-mtime
-f, --fix-datestamps
--degmins
-h, --help
-V, --version
EXAMPLES¶
To correlate all photos in a directory taken in western Europe in the summer (i.e., UTC-2):
gpscorrelate -g Test.gpx -z 2 *.jpg
To 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
To correlate a photo taken from a camera with a fast clock (i.e., the clock was 77 seconds ahead of GPS time):
gpscorrelate -g Test.gpx -O -77 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 at Ulmer Münster:
gpscorrelate -l 48.398620,9.991417,522 -z 2 ulm.jpg
Correlate images taken from a dashcam, adding direction tags:
gpscorrelate --heading --max-dist 5 --max-heading 90 --direction 0 -g Test.gpx *.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
COPYRIGHT¶
Copyright © 2006-2023 Stefano Zacchiroli <zack@debian.org>, Till Maas, Dan Fandrich
19 Sep 2022 | gpscorrelate 2.1 |