Simple command-line tool to add GPS info from a GPX file to EXIF tags in images
Project description
gpx2exif
Simple command-line tool to add GPS info from a GPX file to EXIF tags in local images or to images hosted on Flickr
Motivation
I use Geopaparazzi on my Android phone to log GPS positions during a walk or hike. The app can export into GPX format, which gives the itinerary, as well as the times for my positions at a relatively high temporal resolution. This is useful for making maps or writing a guide after the fact. I also wanted to make it easier to know the location of the photos taken during the walk and have them show up on the Flickr map. Since my camera doesn't have any GPS logging equipment, I made this tool in order to add the GPS information to the photo EXIF tags based on the GPX tracking points.
I also had some GPX recordings corresponding to Flickr images that I had uploaded before I made this tool, so I have also added a way to set the location of existing Flickr images based on a GPX file.
Install
The tool requires Python 3.6+.
To install, launch :
pip install gpx2exif
The command above will install the gpx2exif
Python library and its dependencies. The library includes a command-line script, also named gpx2exif
, whose functionality is described below.
Time
Correspondence between time in images and GPX
In the tool, the time in an image is first shifted using the value for the --delta
option if present. This option can be used to correct for the time drift in the camera relative to the GPS logger or correct the time zone (in the latter case the --delta-tz
option is preferred; See below). The goal is to align the times in the images with the times in the GPX, assumed to be in UTC. The corrected image time is then used to extract a Lat / Lon position from the GPX file (which is essentially a mapping from time to position), which is then added to the EXIF metadata of the image.
There is no switch to shift the time for the GPX file like there is for images: The GPX is assumed to be the reference.
EXIF image time
Time EXIF tag
The time used for an image is taken from the Date Time Original EXIF metadata tag. In Adobe Bridge, it can be shifted as needed in the UI. It can be also shifted using the --delta
and --delta-tz
options using gpx2exif
.
Time zone
There is no standard time zone tag in EXIF. Some cameras will set the Offset Time Original tag to a time shift (something like "+02:00"), which, by default, is read by the tool in order to set a zone. If this tag is not present, the zone of the times in the images is assumed to be UTC ("+00:00"). In that case, if the times in the images are actually in local time, the --delta-tz
option must be used to compensate. The --ignore-offset
switch can also be used to make the tool ignore the Offset Time Original tag even if present (for instance, if it is wrong).
For example, if the local time is in the "Europe/Paris" time zone aka GMT+1 during winter, it is equivalent to an Offset Time Original of "+01:00". This means that, if the time in the image is 11:15am in local time, it is 10:15am in UTC. If the Offset Time Original is not present (or is ignored), then the --delta-tz
option must be set to -1h
to compensate: The 11:15am found in the EXIF tag is considered to be in UTC but, actually, in UTC, it should be 10:15am so the time shift must be set to minus 1 hour. However, if the Offset Time Original is present and set to "+01:00", gpx2exif
will set the delta automatically (by default) to -1h
.
Drift and time zone shifts
If both --delta-tz
and --delta
are present, they are added together to obtain the shift for conversion to UTC.
They are basically interchangeable except in the case when the --update-time
switch is used: In that case, if both options are present, the times in the images will be updated only using the value of the --delta
option. The reason is that it is assumed that the times in the images should be in local time, whereas the addition of --delta-tz
and --delta
result in a time in UTC: The --delta-tz
sets the timezone and the --delta
corrects the drift.
Flickr image time
Time attribute
The time used for a Flickr image is the Date Taken attribute from the Flickr API. Usually it corresponds to the Date Time Original of the EXIF tag of the original photo but it can also be updated manually through the UI (Organizr).
Time zone
There is no timezone for the Date Taken attribute on Flickr and therefore the time is asssumed to be UTC (just like when the offset is missing from the EXIF tags for images on disk). Use the --delta
or -delta-tz
option to compensate (see above).
Format for time shift and tolerance
The time shift (--delta
switch) and tolerance (--tolerance
switch) are time intervals. They can be expressed using a string in a simple format. For example:
1h23m54s
It is possible to specify only seconds (s) or minutes (m) or hours (h) or any combination but the order (h then m then s) must be kept. No space is allowed.
The --delta
switch can be present multiple times. For example, one to set the time zone and that will not change (or very infrequently, like on DST switch days) between runs of gpx2exif
and one set to the time drift of the camera, which can change often (additional 5 to 10 seconds of drift every session with my Fujifilm camera). gpx2exif
will add the two together to compute a single delta for the run.
The time shift can also be negative. For example:
-23m
Options
To get some help about the arguments to the command, just launch with the --help option:
~$ gpx2exif --help
Usage: gpx2exif [OPTIONS] COMMAND [ARGS]...
Add location information to images on disk or on Flickr based on a GPX file
Options:
--debug Flag to activate debug mode
--help Show this message and exit.
Commands:
flickr
image
image subcommand
The image subcommand allows to synch a GPX file with an image file or a folder of image files on a local disk :
~$ gpx2exif image --help
Usage: gpx2exif image [OPTIONS] GPX_FILE IMAGE_FILE_OR_DIR
Add GPS EXIF tags to local images based on a GPX file
Options:
-d, --delta TEXT Time shift to apply to the photo times to
match the date in GPX (see documentation for
format). Multiple possible.[default: no
shift]
-d, --delta-tz TEXT Time zone offset to apply to the photo times
to match the date in GPX (see documentation
for format). If present, assumes --ignore-
offset. [default: no shift (timezone of the
image if present)]
-t, --tolerance TEXT Tolerance if time of the photo is not inside
the time range of the GPX track. (default:
10s)
-o, --ignore-offset Flag to indicate that the OffsetTimeOriginal
should not be used (time of images is
assumed UTC). Use --delta to compensate for
both timezone and drift.
-c, --clear Flag to indicate that the times of the
photos should be cleared if no position can
be computed.
-k, --kml TEXT Path for a KML output file with placemarks
for the photos (useful for checking the
delta)
--update-images / --no-update-images
Flag to indicate that the images should not
be udpated and only a KML will generated
-u, --update-time / --no-update-time
Flag to indicate that the times of the
photos should be updated according to the
delta.
--kml_thumbnail_size INTEGER Pixel size of the image popup in the KML
--help Show this message and exit.
flickr subcommand
~$ gpx2exif flickr --help
Usage: gpx2exif flickr [OPTIONS] GPX_FILE FLICKR_ALBUM_URL
Add location information to Flickr images based on a GPX file
Options:
-d, --delta TEXT Time shift to apply to the photo times to
match the date in GPX (see documentation for
format). Multiple possible.[default: no
shift]
-d, --delta-tz TEXT Time zone offset to apply to the photo times
to match the date in GPX (see documentation
for format). If present, assumes --ignore-
offset. [default: no shift (timezone of the
image if present)]
-t, --tolerance TEXT Tolerance if time of the photo is not inside
the time range of the GPX track. (default:
10s)
-c, --clear Flag to indicate that the times of the
photos should be cleared if no position can
be computed.
-k, --kml TEXT Path for a KML output file with placemarks
for the photos (useful for checking the
delta)
--update-images / --no-update-images
Flag to indicate that the images should not
be udpated and only a KML will generated
--kml_thumbnail_size INTEGER Pixel size of the image popup in the KML
--api_key TEXT Flickr API key [required]
--api_secret TEXT Flickr API secret [required]
--config FILE Path to optional config file for the Flickr
API credentials [default :
/Users/guilhem/Library/Application
Support/gpx2exif/flickr_api_credentials.txt]
--help Show this message and exit.
Flickr API permision
- The API keys and secrets can be obtained by registering a non-commercial application with Flickr at https://www.flickr.com/services/api/misc.api_keys.html Since the API has limits on how many calls can be made per hour, I cannot share my own key.
- A config file is optional and, if present, can contain values for the
api_key
andapi_secret
arguments. It should be a text file with the content like this:
api_key="<Flickr API Key>"
api_secret="<Flickr API Secret>"
(the quotes should be present)
- The default location depends on the OS (the one shown above is for my macOS machine) but can be shown with the
--help
switch. That location can be overriden with the--config
option. - If there is no config file, the key and secret can be passed as options on the command line or as environment variables (
FLICKR_API_KEY
andFLICKR_API_SECRET
).
Log in to Flickr and authorize the application
The first time the tool is run on the command-line, a token for accessing the API must be generated. It is pretty straightforward:
- A web page in the default browser will open.
- If not logged in to Flickr, a Flickr login screen will be presented in order to log in to Flickr.
- Then a request to grant permission to the application is made: The permission is only given for the specific API key obtained when registering yourself.
- Once permission has been granted by the logged in user, a 9-digit code will be displayed: It needs to be copied and pasted on the command line after the prompt "Verifier code:".
After that process, an access token will be cached inside an oauth-tokens.sqlite
file stored on the same directory as the default location of the API key config file (which can vary depending on the OS ; See above).
As long as the token is cached, there will be no need no login again for subsequent runs (that is until the token expires).
The tool will run with the permission of the user that logged in. In order to switch user, the oauth-tokens.sqlite
will need to be deleted.
Examples
Basic usage
The following command will synch the location data found in the GPX file with a single image, moving forward the time in the image by 2 minutes and 25 seconds:
gpx2exif image geopaparazzi_20200315_183754.gpx dsc004239.jpg --delta 2m25s
After running this command, the photo will be updated with the location of the GPX track point that is the closest in time.
Folder
Instead of a single file, it is possible to pass a folder:
gpx2exif image geopaparazzi_20200315_183754.gpx photos --delta 2m25s
Flickr
You must get the URL of an album from Flickr.
gpx2exif flickr geopaparazzi_20200315_183754.gpx https://www.flickr.com/photos/o_0/albums/72157713927736642 --delta 2m25s
(the API key and secret come from a config file and do not need to be passed to the command)
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file gpx2exif-9.tar.gz
.
File metadata
- Download URL: gpx2exif-9.tar.gz
- Upload date:
- Size: 18.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.0.0.post20200309 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.8.1
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 628f8fe8ef43aea72138c5a402af47c202bafc588d98716e1d8f85ed806042cb |
|
MD5 | d12f5979a49441846f4286f64fd1ef85 |
|
BLAKE2b-256 | 6e4be9596266c07414c5c2af9b06e142c7901f11411f28b2cb6390d333eb0c3f |
File details
Details for the file gpx2exif-9-py3-none-any.whl
.
File metadata
- Download URL: gpx2exif-9-py3-none-any.whl
- Upload date:
- Size: 28.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.0.0.post20200309 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.8.1
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4e838eac2b898ad015a1148ed560cecc8f7bf5dfeeebbe0b147d446e23ce585c |
|
MD5 | 00d08aa19fcc8ff2bffe747654a7a40e |
|
BLAKE2b-256 | 595407e478f1085210f3fe32f35d87fcfb6e87bd19d4000efe87e37e297f0559 |