table of contents
GPSCORRELATE(1) | gpscorrelate 2.0 | 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] [-M | --no-mtime] [--degmins] [-g file.gpx | [-l | --latlong] latitude,longitude[,elevation]] image.jpg...
gpscorrelate -s | --show | -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. 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 bug in that it does not parse numbers correctly in locales that use other than "." as a decimal separator.
-s, --show
-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 the accuracy of the location is paramount and you would rather not correlate a position for a photo at all if the nearest 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.
-t, --ignore-tracksegs
-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
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
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-2019 Stefano Zacchiroli <zack@debian.org>, Till Maas, Dan Fandrich
24 Oct 2019 | gpscorrelate 2.0 |