1GPSCORRELATE(1) gpscorrelate 2.0 GPSCORRELATE(1)
2
3
4
6 gpscorrelate - correlates digital images with GPS data filling EXIF
7 fields
8
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
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
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
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
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
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
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
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)