README.md 5.47 KB
Newer Older
1 2
# KGeoTag

Tobias Leupold's avatar
Tobias Leupold committed
3
If you are reading this on GitHub, be aware that this is just a mirror. The real code repository can be found at https://invent.kde.org/graphics/kgeotag.
4

Tobias Leupold's avatar
Tobias Leupold committed
5 6
## What is it?

Tobias Leupold's avatar
Tobias Leupold committed
7
KGeoTag is a Free/Libre Open Source photo geotagging program. It's written in C++/[Qt](https://www.qt.io/) and uses the [KDE Frameworks](https://api.kde.org/frameworks/). It's published under the terms of the [GNU General Public License (GPL)](https://www.gnu.org/licenses/#GPL).
Tobias Leupold's avatar
Tobias Leupold committed
8

Tobias Leupold's avatar
Tobias Leupold committed
9
## What is "Geotagging"?
Tobias Leupold's avatar
Tobias Leupold committed
10

Tobias Leupold's avatar
Tobias Leupold committed
11
Photos (e. g. JPEG images) contain metadata like the creation date, camera information etc. Those are either stored in the so-called [Exif header](https://en.wikipedia.org/wiki/Exif), in an [XMP sidecar file](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform) or in both. This data can also represent geographic coordinates so that it's replicable where the images were taken.
Tobias Leupold's avatar
Tobias Leupold committed
12

Tobias Leupold's avatar
Tobias Leupold committed
13
Most cameras don't have GPS receivers, so, most can't save coordinates when taking images. A common approach is to e. g. carry a small GPS logging device along, which records a track all the time. Later on, the images' dates can be compared to the GPS log's points' dates to figure out where an image was taken.
Tobias Leupold's avatar
Tobias Leupold committed
14

Tobias Leupold's avatar
Tobias Leupold committed
15 16 17
If one knows for sure where the respective photo was taken, it's also possible to assign coordinates to the images manually.

## Geotagging with KGeoTag
Tobias Leupold's avatar
Tobias Leupold committed
18

Tobias Leupold's avatar
Tobias Leupold committed
19 20 21 22
### Supported file formats

KGeoTag currently supports The following image formats: [JPEG](https://en.wikipedia.org/wiki/JPEG), [PNG](https://en.wikipedia.org/wiki/Portable_Network_Graphics), [WebP](https://en.wikipedia.org/wiki/WebP), [TIFF](https://en.wikipedia.org/wiki/TIFF), [OpenRaster](https://en.wikipedia.org/wiki/OpenRaster) and [Krita Document](https://en.wikipedia.org/wiki/Krita).

Tobias Leupold's avatar
Tobias Leupold committed
23 24
Geodata can be loaded from (uncompressed) [GPX](https://en.wikipedia.org/wiki/GPS_Exchange_Format) files.

Tobias Leupold's avatar
Tobias Leupold committed
25 26
### Assigning images

Tobias Leupold's avatar
Tobias Leupold committed
27
KGeoTag offers multiple ways to assign coordinates to images:
Tobias Leupold's avatar
Tobias Leupold committed
28 29 30

#### Automatic tagging

Tobias Leupold's avatar
Tobias Leupold committed
31 32 33
The most convenient approach is automatic matching using geodata provided by GPX files. Those can be loaded and displayed on a map. Using this data, images can be assigned with matching geographic coordinates by finding (more or less) exact chronological matches, or by interpolating a likely position if no exact match can be found.

Normally, the images only provide a time and date, but no timezone. Thus we need to set one to make an assignment possible. The presumably correct timezone is detected from the geographic location of the GPX file, but it can also be set manually.
Tobias Leupold's avatar
Tobias Leupold committed
34 35 36 37 38 39

If altitude values aren't set in the dataset or they are not accurate enough, they can be looked up using opentopodata.org (see below).

The clocks of cameras mostly aren't radio-controlled and often have a slight offset. If the images' dates have a time drift due to the camera's clock being not exactly in sync with the GPS data (which is assumed to be correct), a deviation can be defined. It then will be considered when searching for matches, and can also be used to fix the images' dates.

#### Drag and drop interface
Tobias Leupold's avatar
Tobias Leupold committed
40

Tobias Leupold's avatar
Tobias Leupold committed
41
Another option is tagging images via drag and drop. One or more images can be selected and dropped onto the map, to their respective location (possibly also guided by some GPX track). Elevations can't be ascertained this way, so either, they are left to be "0 m" (sea level), entered manually or looked up via opentopodata.org (either automatically or manually, see below).
Tobias Leupold's avatar
Tobias Leupold committed
42

Tobias Leupold's avatar
Tobias Leupold committed
43
#### Assigning images to bookmarks
Tobias Leupold's avatar
Tobias Leupold committed
44

Tobias Leupold's avatar
Tobias Leupold committed
45
For places frequently assigned to images (like one's home, where one doesn't carry a GPS logger), bookmarks can be defined. Images can then be assigned to the respective coordinates easily.
Tobias Leupold's avatar
Tobias Leupold committed
46

Tobias Leupold's avatar
Tobias Leupold committed
47 48 49 50
#### Manual assignment

It's also possible to enter coordinates for one or more images by hand. The altitudes can be either looked up automatically using opentopodata.org (see below), or also be entered manually.

Tobias Leupold's avatar
Tobias Leupold committed
51
### Setting or looking up elevation information
Tobias Leupold's avatar
Tobias Leupold committed
52

Tobias Leupold's avatar
Tobias Leupold committed
53
Altitudes can always be set maually. Alternatively, the altitudes can also be looked up querying different elevation datasets using [opentopodata.org](https://www.opentopodata.org/)'s API.
Tobias Leupold's avatar
Tobias Leupold committed
54

Tobias Leupold's avatar
Tobias Leupold committed
55
The preset it to use the [ASTER](https://asterweb.jpl.nasa.gov/gdem.asp) dataset. This one covers the whole globe. Others can be used as well, cf. [opentopodata.org's homepage](https://www.opentopodata.org/#public-api).
Tobias Leupold's avatar
Tobias Leupold committed
56

Tobias Leupold's avatar
Tobias Leupold committed
57
By default, such a server lookup has to be triggered manually. It's also possible to enable automated altitude lookups for all images dropped on the map (which yields geographic coordinates but no elevation) and coordinates entered manually.
Tobias Leupold's avatar
Tobias Leupold committed
58

Tobias Leupold's avatar
Tobias Leupold committed
59
### Making the data persistent
60

Tobias Leupold's avatar
Tobias Leupold committed
61
Finally, the assigned coordinates can be saved. KGeoTag can either write them to the images' Exif header (which will obviously alter the respective files), to XMP sidecar files (leaving the original files untouched) or to both. By default, a backup of each original file is created if it will be changed during the write process.
Tobias Leupold's avatar
Tobias Leupold committed
62

Tobias Leupold's avatar
Tobias Leupold committed
63 64 65
This way, the geodata assignment is made persistent and also accessible for other geodata-aware applications (like e. g. [KPhotoAlbum](https://www.kphotoalbum.org/)).

If a time drift has been identified and a deviation has been given, the images' dates and times also can be fixed whilst saving.
Tobias Leupold's avatar
Tobias Leupold committed
66

Tobias Leupold's avatar
Tobias Leupold committed
67
## Getting in touch
Tobias Leupold's avatar
Tobias Leupold committed
68

Tobias Leupold's avatar
Tobias Leupold committed
69
The IRC channel of the project is [#kde-kgeotag](irc://chat.freenode.net/kde-kgeotag), and there's also a [mailing list](https://mail.kde.org/cgi-bin/mailman/listinfo/kgeotag/).
Tobias Leupold's avatar
Tobias Leupold committed
70

Tobias Leupold's avatar
Tobias Leupold committed
71
Everybody is invited to participate in KGeoTag's development! You don't have to be able to write code to do so. All testing and feedback is greatly appreciated!