Warning, /graphics/kgeotag/doc/overview.docbook is written in an unsupported language. File is not indexed.

 <!-- SPDX-FileCopyrightText: 2022 Tobias Leupold <tl at stonemx dot de>
 
      SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 <chapter id="overview">
 
 <title>Overview</title>
 
 <section>
 
 <title>What is it?</title>
 
 <para>
 KGeoTag is a Free/Libre Open Source photo geotagging program. It's written in C++/<ulink url="https://www.qt.io/">Qt</ulink> and uses the <ulink url="https://api.kde.org/frameworks/">KDE Frameworks</ulink>. It's published under the terms of the <ulink url="https://www.gnu.org/licenses/#GPL">GNU General Public License (GPL)</ulink>.
 </para>
 
 </section>
 
 <section>
 
 <title>What is "Geotagging"?</title>
 
 <para>
 Photos (&eg; JPEG images) contain metadata like the creation date, camera information &etc; Those are either stored in the so-called <ulink url="https://en.wikipedia.org/wiki/Exif">Exif header</ulink>, in an <ulink url="https://en.wikipedia.org/wiki/Extensible_Metadata_Platform">XMP sidecar file</ulink> or in both. This data can also represent geographic coordinates so that it's replicable where the images were taken.
 </para>
 
 <para>
 Most cameras don't have GPS receivers, so, most can't save coordinates when taking images. A common approach is to &eg; carry a small GPS logging device along (or nowadays also using a smartphone ;-)), 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.
 </para>
 
 <para>
 If one knows for sure where the respective photo was taken, it's also possible to assign coordinates to the images manually.
 </para>
 
 </section>
 
 <section>
 
 <title>Geotagging with KGeoTag</title>
 
 <section>
 
 <title>Supported file formats</title>
 
 <para>
 KGeoTag currently supports The following image formats: <ulink url="https://en.wikipedia.org/wiki/JPEG">JPEG</ulink>, <ulink url="https://en.wikipedia.org/wiki/Portable_Network_Graphics">PNG</ulink>, <ulink url="https://en.wikipedia.org/wiki/WebP">WebP</ulink>, <ulink url="https://en.wikipedia.org/wiki/TIFF">TIFF</ulink>, <ulink url="https://en.wikipedia.org/wiki/OpenRaster">OpenRaster</ulink> and <ulink url="https://en.wikipedia.org/wiki/Krita">Krita Document</ulink>, as well as some TIFF-based RAW image formats: <ulink url="https://en.wikipedia.org/wiki/Raw_image_format">Canon Raw v2</ulink> (.cr2), <ulink url="https://www.nikonusa.com/en/learn-and-explore/a/products-and-innovation/nikon-electronic-format-nef.html">Nikon Electronic Format</ulink> (.nef) and <ulink url="https://helpx.adobe.com/camera-raw/digital-negative.html">Adobe Digital Negative</ulink> (.dng).
 </para>
 
 <para>
 Geodata can be loaded from (uncompressed) <ulink url="https://en.wikipedia.org/wiki/GPS_Exchange_Format">GPX</ulink> files.
 </para>
 
 </section>
 
 <section>
 
 <title>Assigning images</title>
 
 <para>
 KGeoTag offers multiple ways to assign coordinates to images:
 </para>
 
 <section>
 
 <title>Automatic tagging</title>
 
 <para>
 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.
 </para>
 
 <para>
 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.
 </para>
 
 <para>
 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).
 </para>
 
 <para>
 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.
 </para>
 
 </section>
 
 <section>
 
 <title>Drag and drop interface</title>
 
 <para>
 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).
 </para>
 
 </section>
 
 <section>
 
 <title>Assigning images to bookmarks</title>
 
 <para>
 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.
 </para>
 
 </section>
 
 <section>
 
 <title>Manual assignment</title>
 
 <para>
 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.
 </para>
 
 </section>
 
 </section>
 
 <section>
 
 <title>Setting or looking up elevation information</title>
 
 <para>
 Altitudes can always be set manually. Alternatively, the altitudes can also be looked up querying different elevation datasets using <ulink url="https://www.opentopodata.org/">opentopodata.org</ulink>'s API.
 </para>
 
 <para>
 The preset is to use the <ulink url="https://asterweb.jpl.nasa.gov/gdem.asp">ASTER</ulink> dataset. This one covers the whole globe. Others can be used as well, cf. <ulink url="https://www.opentopodata.org/#public-api">opentopodata.org's homepage</ulink>.
 </para>
 
 <para>
 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.
 </para>
 
 </section>
 
 <section>
 
 <title>Making the data persistent</title>
 
 <para>
 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.
 </para>
 
 <para>
 This way, the geodata assignment is made persistent and also accessible for other geodata-aware applications (like &eg; <ulink url="https://www.kphotoalbum.org/">KPhotoAlbum</ulink>).
 </para>
 
 <para>
 If a time drift has been identified and a deviation has been given, the images' dates and times also can be fixed whilst saving.
 </para>
 
 </section>
 
 </section>
 
 </chapter>