# GPS Correlate

## What is it?

Digital cameras are cool. So is GPS. And, EXIF tags are really cool too.

What happens when you merge the three? You end up with a set of photos taken with a digital camera that are "stamped" with the location at which they were taken.

GPS Correlate takes a GPS track stored by any of a number of GPS devices and phone apps and correlates the time stamp of a digital photo with the location of the track at that same moment. The location of the image is then stamped directly into the image file using the appropriate EXIF GPS tags. The resulting image then contains not just the time the photo was taken but its exact location, too. The location is used by various other applications and services (such as Google Photos) to display a map of where the photo was taken.

A typical use case would be to start a GPS tracking app on the phone in your pocket while taking pictures. After the shoot, download the track in GPX format to your computer along with the photos, then use gpscorrelate to combine the two.

Most high-end DSLR and mirrorless cameras these days (as well as smartphones) have built-in GPS receivers that tag pictures automatically, but entry level models often do not. There are also cases where GPS signals are not available, such as inside some airplanes. In this latter case, the airplane's course can often be downloaded from web sites like FlightAware, converted to GPX format using gpsbabel, then correlated with pictures taken on board the plane with your camera.

GPS Correlate comes in two flavours: a graphical version for point-and-click convenience, or a command-line version for easy batch correlation.

## Documentation

- GPS Photo Correlation Concepts
- Manual page of the command line client
- Usage of the GUI version
- Readme file
- Changelog

## Installation

gpscorrelate is available in a number of Linux distributions and other Open Source operating systems; use your normal package manager to install it. It's also available as a Flatpak from Flathub that can be installed on almost any Linux distro. You can compile it yourself from source for other platforms like *BSD and Windows.

## Source Code

Source code is available from the Github project. Download the latest release.

## Bug Reports

If you've found a problem with gpscorrelate, please open an issue.

Important Note for users before 1.5.2

Prior to version 1.5.2, there was a bug in gpscorrelate that caused gpscorrelate to incorrectly parse dates. The result is that the internal date format was one month out (ie, December was considered as the following January, and January was considered as February).

This did not affect the matching of photos, as the GPX data and the EXIF data were passed through the same buggy conversion.

When writing out GPS data, gpscorrelate wrote a GPSTimeStamp and a GPSDateStamp tag, which had the UTC GPS Time and Date of the match. The DateStamp and TimeStamp tags were written incorrectly (from two distinctly separate bugs), and was around one month ahead of the real time. The original date and time of the photo were not modified.

Version 1.5.2 introduces a new command line option, --fix-datestamps. Running gpscorrelate with this option and then a series of JPEG files that were tagged will detect and correct the problem. This will modify the GPSDateStamp and GPSTimeStamp tag to be correct, but only if this is required. You can run gpscorrelate with the -n (no write) option just to see which files are affected without making any changes. When correcting files, --no-mtime (don't change the mtime of the file) is implied.

When using --fix-datestamps, you will also need to use --timeadd to specify the difference between the photo time and UTC.

## More information

For more information, later versions, or bug reports, please visit github.com/dfandrich/gpscorrelate. To see the latest version of this documentation on-line, visit dfandrich.github.io/gpscorrelate.

En Français