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

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

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

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

COPYRIGHT

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