1GPSCORRELATE(1)                gpscorrelate 2.0                GPSCORRELATE(1)
2
3
4

NAME

6       gpscorrelate - correlates digital images with GPS data filling EXIF
7       fields
8

SYNOPSIS

10       gpscorrelate [-z | --timeadd +/-HH[:MM]] [-O | --photooffset seconds]
11                    [-i | --no-interpolation] [-v | --verbose] [-d |
12                    --datum datum] [-n | --no-write] [-R | --replace] [-m |
13                    --max-dist time] [-t | --ignore-tracksegs] [-M |
14                    --no-mtime] [--degmins] [-g file.gpx |
15                    [-l | --latlong] latitude,longitude[,elevation]]
16                    image.jpg...
17
18       gpscorrelate -s | --show | -o | --machine  image.jpg...
19
20       gpscorrelate {-r | --remove} [-M | --no-mtime] image.jpg...
21
22       gpscorrelate {-f | --fix-datestamps} {-z | --timeadd +/-HH[:MM]}
23                    image.jpg...
24
25       gpscorrelate -V | --version | -h | --help
26

DESCRIPTION

28       This manual page documents the gpscorrelate command. There is extended
29       documentation available in HTML format; see below.
30
31       gpscorrelate is a program that acts on digital images in JPEG format,
32       filling in the EXIF (Exchangeable Image File Format) fields related to
33       GPS (Global Positioning System) information. Source for the GPS data is
34       a GPX (GPS Exchange Format) file, which records GPS location
35       information in an XML-based format. The act of filling those fields is
36       referred to as correlation.
37
38       If GPS data are available at the precise moment the image was taken
39       (with a 1-second granularity) the GPS data are stored unmodified in
40       EXIF fields. If they are not, linear interpolation of GPS data
41       available at moments before and after the image was taken can be used.
42       A measure of the approximate accuracy of the GPS location reading is
43       preserved when written into the image.
44

OPTIONS

46       These programs follow the usual GNU command line syntax, with long
47       options starting with two dashes (`-'). A summary of options is
48       included below.
49
50       -g, --gps file.gpx
51           Correlate images using the specified GPX file containing GPS track
52           points. This option can be given many times to specify multiple GPX
53           files. For each photo being correlated, the first file containing a
54           track covering the time the photo was taken will be the one used.
55           All <trk> segments in each file are used.
56
57       -l, --latlong latitude,longitude[,elevation]
58           Provide a specific geographic coordinate to use for all images
59           instead correlating along a path in a GPX file. The format must be
60           of the general form latitude,longitude,elevation where latitude and
61           longitude must each be in either decimal form, such as -123.45678
62           or in degrees/minutes/seconds form, such as -123°45'67.8" or
63           -123d45m67s. Providing an elevation is optional. Each component can
64           be separated by commas, spaces or tabs.
65
66           Note that this option has a known bug in that it does not parse
67           numbers correctly in locales that use other than "." as a decimal
68           separator.
69
70       -s, --show
71           Only show the GPS data already in the given image's EXIF tags
72           instead of correlating them.
73
74       -o, --machine
75           Only show the GPS data of the given images in a machine-readable
76           CSV format. Images without GPS tags are ignored. The fields output
77           are file name, date and time, latitude, longitude, elevation, where
78           the first value is the filename, as passed, the second is the
79           timestamp, and the last three are floating point values with an
80           optional leading plus or minus.
81
82       -r, --remove
83           Remove all GPS EXIF data from the given images. Note that this only
84           removes the GPS tags that the program could add; it does not delete
85           all possible GPS EXIF tags. All other tags are left alone.
86
87       -z, --timeadd +/-HH[:MM]
88           Time to add to GPS points to make them match the timestamps of the
89           images. GPS timestamps are in UTC; image timestamps are generally
90           in local time. Enter the timezone used when taking the images;
91           e.g., +8 for Perth, Western Australia or -2:30 for St. John's,
92           Newfoundland. This defaults to the UTC offset of the local time
93           zone as of the time of the first image processed (versions before
94           1.7 defaulted to 00:00).
95
96       -O, --photooffset seconds
97           Time in seconds to add to the photo timestamp to make it match the
98           GPS timestamp. To determine the number of seconds needed, just
99           create a photograph of your GPS device showing the current time and
100           compare it with the timestamp of your photo file. The EXIF time
101           tags in the image are not modified based on this value.
102
103       -i, --no-interpolation
104           Disable linear interpolation between points. With this flag, the
105           nearest exact point (within --max-dist) is used. Without this flag,
106           photos taken between the time of two recorded GPS coordinates are
107           correlated based on linear interpolation between those two points.
108
109       -v, --verbose
110           Show slightly more information during the image correlation
111           process, such as the GPS data selected for each image.
112
113       -d, --datum datum
114           Specify GPS measurement datum. If not set, WGS-84 is used (TOKYO is
115           another possibility). However, GPX is not supposed to store
116           anything but WGS-84, so this should only ever be needed with the
117           --latlong option.
118
119       -n, --no-write
120           Do not write the correlated EXIF data back into the image. Useful
121           with --verbose to see what would happen during image correlation.
122
123       -R, --replace
124           Overwrite any existing GPS tags in the file. Without this option,
125           any file that already contains GPS tags will be skipped.
126
127       -m, --max-dist time
128           Maximum time in seconds from the photo time which a logged GPS
129           point can refer and still be used for correlation. This defaults to
130           0, which means to disable this check. Only one of the two points
131           need be within this range for correlation to take place.
132
133           If the accuracy of the location is paramount and you would rather
134           not correlate a position for a photo at all if the nearest GPS
135           coordinates were recorded too long ago in the past or too far into
136           the future (relative to when the photo was taken), then set this to
137           a nonzero value.
138
139       -t, --ignore-tracksegs
140           Interpolate between track segments, too. Generally, track segments
141           show multiple sessions of GPS logging; between them is generally
142           when the GPS was not logging. Since interpolation honours the
143           --max-dist flag, even track segments with wide time gaps can safely
144           be used if both flags are set. Without this flag, photos taken
145           within the time gap between two <trkseg> tracks in the GPX file are
146           not correlated.
147
148       -M, --no-mtime
149           Do not change the last modification time of changed files.
150
151       -f, --fix-datestamps
152           Fix broken GPS datestamps written with gpscorrelate versions <
153           1.5.2 by replacing them with the photo's time stamp. Prior to
154           1.5.2, two bugs wrote the wrong value for the GPSDateStamp and
155           GPSTimeStamp tags. This option will check each supplied filename
156           for the problem and correct it. Use with --no-write to prevent
157           writing these changes (useful for checking for the issue). This
158           option also implies --no-mtime. You will also need to use --timeadd
159           to specify the difference between localtime and UTC time for the
160           supplied photos.
161
162       --degmins
163           Write location as DD MM.MM (instead of the more accurate DD MM
164           SS.SS) as was the default in gpscorrelate versions < 1.5.3. There
165           is no good reason to use this option unless some broken program
166           expects this style.
167
168       -h, --help
169           Only show a summary of options.
170
171       -V, --version
172           Only print the gpscorrelate version number and copyright
173           information.
174

EXAMPLES

176       To correlate all photos in a directory taken in western Europe in the
177       summer (i.e., UTC-2):
178
179       gpscorrelate -g Test.gpx -z 2 *.jpg
180
181       To correlate all photos in a directory taken in Italy, switching to
182       UTC-2 or UTC-1 depending on the daylight savings time in effect when
183       the first picture in the list was taken:
184
185       env TZ=Europe/Rome gpscorrelate -g Test.gpx *.jpg
186
187       Correlate all photos in a directory from a track spread out over two
188       different track files and taken in the computer's current time zone,
189       interpolating between segments and between files while ignoring photos
190       taken too far away from a recorded point, without changing the file
191       time stamp of the files, while showing details of the process:
192
193       gpscorrelate -g track1.gpx -g track2.gpx -m 120 -t -M -v *.jpg
194
195       To correlate a photo taken from a camera with a fast clock (i.e., the
196       clock was 77 seconds ahead of GPS time):
197
198       gpscorrelate -g Test.gpx -O -77 photo.jpg
199
200       Show existing GPS tags in a photo:
201
202       gpscorrelate --show photo.jpg
203
204       Show existing GPS tags in a photo and output in CSV format:
205
206       gpscorrelate --show --machine photo.jpg
207
208       Remove GPS tags from photos:
209
210       gpscorrelate --remove *.jpg
211
212       Add a GPS location tag to a photo taken at Ulmer Münster:
213
214       gpscorrelate -l 48.398620,9.991417,522 -z 2 ulm.jpg
215

EXIT STATUS

217       gpscorrelate returns 0 in case of success, 1 in case of major error
218       (such as a read or write error) and 2 in case of minor error (such as
219       the given GPS track not covering the time of an image).
220

SEE ALSO

222       gpsd(1), gpsbabel(1), gpxlogger(1), cgpxlogger(1).
223
224       The documentation of gpscorrelate in HTML format is available on the
225       filesystem at /usr/local/share/doc/gpscorrelate.
226

LICENSE

228       This manual page was initially written by Stefano Zacchiroli
229       <zack@debian.org> for the Debian(TM) system. It was extended by Till
230       Maas <opensource@till.name> and Dan Fandrich <dan@coneharvesters.com>.
231       Permission is granted to copy, distribute and/or modify this document
232       under the terms of the GNU General Public License, Version 2 or any
233       later version published by the Free Software Foundation.
234

AUTHOR

236       Stefano Zacchiroli
237           Author.
238
240       Copyright © 2006-2019 Stefano Zacchiroli <zack@debian.org>, Till Maas,
241       Dan Fandrich
242
243
244
245gpscorrelate 2.0                  24 Oct 2019                  GPSCORRELATE(1)
Impressum