1GPSCORRELATE(1) gpscorrelate 2.0 GPSCORRELATE(1)
2
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 gpscorrelate -s | --show | -o | --machine image.jpg...
19 gpscorrelate {-r | --remove} [-M | --no-mtime] image.jpg...
21 gpscorrelate {-f | --fix-datestamps} {-z | --timeadd +/-HH[:MM]}
23 image.jpg...
24 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 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 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 -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 -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 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 -s, --show
71 Only show the GPS data already in the given image's EXIF tags
72 instead of correlating them.
73 -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 -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 -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 -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 -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 -v, --verbose
110 Show slightly more information during the image correlation
111 process, such as the GPS data selected for each image.
112 -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 -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 -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 -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 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 -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 -M, --no-mtime
149 Do not change the last modification time of changed files.
150 -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 --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 -h, --help
169 Only show a summary of options.
170 -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 gpscorrelate -g Test.gpx -z 2 *.jpg
180 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 env TZ=Europe/Rome gpscorrelate -g Test.gpx *.jpg
186 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 gpscorrelate -g track1.gpx -g track2.gpx -m 120 -t -M -v *.jpg
194 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 gpscorrelate -g Test.gpx -O -77 photo.jpg
199 Show existing GPS tags in a photo:
201 gpscorrelate --show photo.jpg
203 Show existing GPS tags in a photo and output in CSV format:
205 gpscorrelate --show --machine photo.jpg
207 Remove GPS tags from photos:
209 gpscorrelate --remove *.jpg
211 Add a GPS location tag to a photo taken at Ulmer Münster:
213 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 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
242gpscorrelate 2.0 24 Oct 2019 GPSCORRELATE(1)