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
           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 bug in that it does not parse numbers correctly in locales that use
           other than "." as a decimal separator.

       -s, --show
           Only show the GPS data already in the given image's EXIF tags instead of correlating them.

       -o, --machine
           Only show the GPS data of the given images in a machine-readable CSV format. 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 UTC
           offset of the local time zone as of the time of the first image processed (versions before 1.7
           defaulted to 00:00).

       -O, --photooffset seconds
           Time in seconds 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 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
           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.

       -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

       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
           Author.

COPYRIGHT

       Copyright © 2006-2019 Stefano Zacchiroli <zack@debian.org>, Till Maas, Dan Fandrich

gpscorrelate 2.0                                   24 Oct 2019                                   GPSCORRELATE(1)