Git commit 16f3124142de5d612b45e3e13af4b40d7fc88860 by Tobias Leupold. Committed on 14/04/2022 at 09:57. Pushed by tleupold into branch 'master'.
Added a handbook stub BUG: 452534 M +11 -1 CMakeLists.txt M +2 -0 ChangeLog.rst M +1 -1 ChangeLog.rst.license A +60 -0 doc/index.docbook A +156 -0 doc/overview.docbook https://invent.kde.org/graphics/kgeotag/commit/16f3124142de5d612b45e3e13af4b40d7fc88860 diff --git a/CMakeLists.txt b/CMakeLists.txt index ce310a8..14acc88 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -36,7 +36,10 @@ add_definitions( ) # Find KDE -find_package(KF5 ${KF5_MIN_VERSION} COMPONENTS CoreAddons I18n XmlGui ConfigWidgets Crash REQUIRED) +find_package(KF5 ${KF5_MIN_VERSION} + COMPONENTS CoreAddons I18n XmlGui ConfigWidgets Crash DocTools + REQUIRED +) find_package(KF5KExiv2 ${KExiv2_MIN_VERSION} REQUIRED) # Find Marble @@ -101,6 +104,13 @@ target_link_libraries(kgeotag Marble ) +# Documentation +kdoctools_create_handbook( + doc/index.docbook + INSTALL_DESTINATION "${KDE_INSTALL_DOCBUNDLEDIR}/en" + SUBDIR kgeotag +) + # Installation install(TARGETS kgeotag ${KDE_INSTALL_TARGETS_DEFAULT_ARGS}) diff --git a/ChangeLog.rst b/ChangeLog.rst index d5d296c..0961863 100644 --- a/ChangeLog.rst +++ b/ChangeLog.rst @@ -1,3 +1,5 @@ +* **New/Bugfix (#452534):** Added a handbook stub. + ==================================================================================================== KGeoTag 1.2.0 released (12.11.2021) ==================================================================================================== diff --git a/ChangeLog.rst.license b/ChangeLog.rst.license index d431ee5..9c563cd 100644 --- a/ChangeLog.rst.license +++ b/ChangeLog.rst.license @@ -1,3 +1,3 @@ -SPDX-FileCopyrightText: 2021 Tobias Leupold <tl at l3u dot de> +SPDX-FileCopyrightText: 2021-2022 Tobias Leupold <tl at l3u dot de> SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/doc/index.docbook b/doc/index.docbook new file mode 100644 index 0000000..a60b98b --- /dev/null +++ b/doc/index.docbook @@ -0,0 +1,60 @@ +<?xml version="1.0" ?> + +<!-- SPDX-FileCopyrightText: 2022 Tobias Leupold <tl at l3u dot de> + + SPDX-License-Identifier: CC-BY-SA-4.0 +--> + +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ + <!ENTITY kgeotag "<application>KGeoTag</application>"> + <!ENTITY kappname "&kgeotag;"> + <!ENTITY package "extragear-graphics"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> + <!ENTITY overview SYSTEM "overview.docbook"> +]> + +<book id="kgeotag" lang="&language;"> + +<bookinfo> + +<title>The &kgeotag; Handbook</title> + +<authorgroup> + +<author> +<firstname>Tobias</firstname> +<surname>Leupold</surname> +</author> + +</authorgroup> + +<copyright> +<year>2022</year> +<holder>Tobias Leupold</holder> +</copyright> + +<date>2022-04-14</date> + +<releaseinfo>1</releaseinfo> + +<abstract> + +<para> +This is a user manual stub for &kgeotag;, the stand-alone photo geotagging program. At the moment, there's not much to see here apart from the general information you can find on <ulink url="https://kgeotag.kde.org/";>KGeoTag's homepage</ulink>, but hopefully, this will change in the future ;-) +</para> + +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>extragear-graphics</keyword> +<keyword>KGeoTag</keyword> +<keyword>Photo geotagging program</keyword> +</keywordset> + +</bookinfo> + +&overview; + +</book> diff --git a/doc/overview.docbook b/doc/overview.docbook new file mode 100644 index 0000000..fda4a93 --- /dev/null +++ b/doc/overview.docbook @@ -0,0 +1,156 @@ +<!-- SPDX-FileCopyrightText: 2022 Tobias Leupold <tl at l3u 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 (e.g. 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 e.g. 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>. +</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 maually. 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 e.g. <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>
