[digikam-doc] digikam: apply patch 0018
Gilles Caulier
null at kde.org
Mon Feb 20 07:35:08 UTC 2017
Git commit 49c323cf2372f43211cc04e77e42a78f14db2bc5 by Gilles Caulier, on behalf of Wolfgang Scheffner.
Committed on 20/02/2017 at 07:34.
Pushed by cgilles into branch 'master'.
apply patch 0018
M +212 -163 digikam/tool-geolocationeditor.docbook
M +3 -1 digikam/using-sidebar-maps.docbook
https://commits.kde.org/digikam-doc/49c323cf2372f43211cc04e77e42a78f14db2bc5
diff --git a/digikam/tool-geolocationeditor.docbook b/digikam/tool-geolocationeditor.docbook
index 1273a15..85b66f8 100644
--- a/digikam/tool-geolocationeditor.docbook
+++ b/digikam/tool-geolocationeditor.docbook
@@ -2,181 +2,230 @@
<chapterinfo>
<abstract>
-<para>
-The Geolocation Editor allows for adding and editing GPS coordinates of picture metadata. The geo-data is stored into the image (EXIF tags) and the location can be displayed in an external browser map.
-</para>
+ <para>
+ The Geolocation Editor allows for adding and editing GPS coordinates of picture metadata. The geo-data is stored into the image (EXIF tags) and the location can be displayed in an internal or external browser map. The Geolocation Editor also offers a <firstterm>reverse geolocation</firstterm> tool.
+ </para>
</abstract>
<keywordset>
-<keyword>GPS</keyword>
-<keyword>Map</keyword>
-</keywordset>
+ <keyword>GPS</keyword>
+ <keyword>Map</keyword>
+ </keywordset>
</chapterinfo>
<title>Geolocation Editor</title>
-<para>
- The <quote>Geolocation Editor</quote> provides the tools to localize pictures
- geographically in the common spherical coordinate system (used by GPS/Galileo).
- Altitude, latitude and longitude are used.
-</para>
-<note><para>
- The tool only works for image formats that have EXIF or XMP metadata supported by
- <ulink url="http://www.exiv2.org">Exiv2 library</ulink>.
-</para></note>
-
-<sect1 id="geolocation-title"> <title>Geolocation</title>
-<para>
-The tool has two methods to mark the pictures with coordinates:
-</para>
-<itemizedlist>
- <listitem>
- <para>Batch correlation of GPS tracking data with a series of images.</para>
- </listitem>
- <listitem>
- <para>Semi-automatic coordinate attribution to single pictures.</para>
- </listitem>
-</itemizedlist>
+ <para>
+ There are three tools regarding geolocation in &digikam;:
+ <orderedlist numeration="arabic">
+ <listitem><para>
+ <!-- The <link linkend="using-mainwindow-mapview">Map View</link> -->
+ The Map View
+ on the Left Sidebar which is the search tool for finding images by their GPS data.
+ </para></listitem>
+ <listitem><para>
+ The Geolocation Editor we describe in this chapter and which is accessible via <menuchoice><shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>G</keycap></keycombo></shortcut><guimenu>Item</guimenu><guimenuitem>Edit Geolocation...</guimenuitem></menuchoice>
+ </para></listitem>
+ <listitem><para>
+ The <link linkend="using-sidebar-maps">Map</link> tab on the Right Sidebar which shows the location of the image on a map and is purely informative.
+ </para></listitem>
+ </orderedlist>
+ All three are based on the &marble; widget.
+ </para>
+
+ <note><para>
+ These tools only work for image formats that have EXIF or XMP metadata supported by
+ <ulink url="http://www.exiv2.org">Exiv2 library</ulink>.
+ </para></note>
+
+ <para>
+ <inlinemediaobject>
+ <imageobject><imagedata fileref="tool-geolocation-editcoords.png" format="PNG" /></imageobject>
+ </inlinemediaobject>
+ </para>
+
+ <para>
+ The <quote>Geolocation Editor</quote> provides the tools to localize pictures geographically in the common spherical coordinate system (used by GPS/Galileo). Altitude, latitude and longitude, speeed, number of satellites, fix type and DOP are editable.
+ </para>
-<sect2 id="geolocation-correlator"> <title>The correlator</title>
- <para>In order to correlate your images with geographic data you need to
- have a GPS tracking information available as a XML file in <literal>gpx</literal>
- format (<application><ulink url="http://www.gpsbabel.org">gpsbabel</ulink></application>
- and <application><ulink url="http://www.ncc.up.pt/gpsman/">gpsman</ulink></application>
- can download and convert tracking data from a GPS device for you).
+ <sect1 id="geolocation-title"> <title>Geolocation</title>
+
+ <para>
+ The editor has two methods to mark the pictures with coordinates:
</para>
+
+ <itemizedlist>
+ <listitem><para>
+ Semi-automatic coordinate attribution to single pictures, accessible via the <guilabel>Details</guilabel> tab on the Right Sidebar.
+ </para></listitem>
+ <listitem><para>
+ Batch correlation of GPS tracking data with a series of images you will find in the
+ <link linkend="geolocation-correlator">GPS Correlator</link> tab.
+ </para></listitem>
+ </itemizedlist>
+
<para>
- <menuchoice><guimenu>Image</guimenu>
- <guimenuitem>Geolocation</guimenuitem>
- <guimenuitem>Correlator</guimenuitem></menuchoice>.
- This interface can correlate a previously selected number of pictures
- with registered GPS tracking information.
+ Furthermore the Right Sidebar offers three more tools:
</para>
- <example id="geolocation-geo-correlation-dialog">
- <title>The geo-correlation dialog based on EXIF date/time and tracking data (gpx format)</title>
- <screenshot><mediaobject><imageobject><imagedata fileref="tool-geolocation-correlate1.png" format="PNG" /> </imageobject></mediaobject></screenshot>
- </example>
- <para>
- Select the images you want to correlate in the application main view,
- then call the menu. The above dialog will show up. To indicate possible
- time/location correlation you have to load a track file with
- <guilabel>Load GPX File</guilabel> that contains GPS data taken at
- the same time and location as the pictures with your camera.
- </para>
- <para>
- When the file is loaded, an automatic correlation is done showing the
- attributed coordinates in red. GPS track data is invariably recorded
- in GMT time, so you need to match the camera time with GMT, which
- can be done with <guilabel>Time Zone</guilabel>. Select the
- <emphasis>camera time zone</emphasis> here!
- </para>
- <para>
- The <guilabel>Max. time gap</guilabel> setting specifies the limit
- within which GPS time and camera time shall be deemed coincident.
- The maximum value is 2000 seconds.
- </para>
- <tip><para>If you have no tracking data for pictures that were taken
- in the same place you can just manually edit a <literal>gpx</literal>
- file and apply it to those images. The 2000 second time gap will then
- correlate all pictures taken within 20 minutes.
- </para></tip>
-
- <para>
- The option <guilabel>Interpolate</guilabel> and <guilabel>Difference
- in min.</guilabel> can be used if there is no match of data. If you
- know that in reality there is a location match despite a larger time gap
- between camera and GPS, you can set this limit here and click on the
- <guilabel>Correlate</guilabel> button to interpolate.
- </para>
- <example id="geolocation-correlation">
- <title>Correlation</title>
- <screenshot><mediaobject><imageobject><imagedata fileref="tool-geolocation-correlate2.png" format="PNG" /> </imageobject></mediaobject></screenshot>
- </example>
- <para>
- 240 minutes is the maximum time difference that can be introduced here.
- </para>
-
-</sect2>
-
-<sect2 id="geolocation-edit-coordinates"> <title>Edit Coordinates</title>
- <example id="geolocation-semi-automatic-attributing">
- <title>Semi-automatic attributing of coordinates through map interaction</title>
- <screenshot><mediaobject><imageobject><imagedata fileref="tool-geolocation-editcoords.png" format="PNG" /> </imageobject></mediaobject></screenshot>
- </example>
- <para>
- The coordinates can be set manually with this dialog. This comes in handy
- if there is a series of photos taken at the same location. Since the
- coordinates are memorized from one dialog call to another, it is as
- easy as clicking on <guilabel>OK</guilabel> to set the previous data
- to the current photo.
- </para>
- <para>
- Otherwise the location can be found and fixed iteratively with the
- displayed map. Click on the region of interest, zoom in, adjust
- location by clicking again, and so on until sufficient accuracy is
- achieved. The altitude must always be entered manually. The map can
- be switched between map mode, satellite image or mixed mode.
- </para>
-</sect2>
-
-<sect2 id="geolocation-manual"> <title>Commandline tagging</title>
- <para>
- Completely outside of the &digikam; context, the are ways to GPS tag images.
- Here is a shell script that uses <command>exiftool</command> to tag a
- batch of images.
- </para>
-
-
-<programlisting>
-#!/bin/sh
-# exiftool wrapper script for easy commandline use. It treats regex files or whole directories.
-#
-# FMT Output
-# "%d deg %d' %.2f"\" 54 deg 59' 22.80"
-# "%d deg %.4f min" 54 deg 59.3800 min
-# "%.6f degrees" 54.989667 degrees
-
-if [ -z $1 ]; then
- echo "Usage: exiftool-gps-wrapper lat long [alt] file || dir (use signed floating coordinates)"
-else
-
- if [ -z "$4" ]; then foo="$3"; alt=0
- else foo="$4"; alt=$3
- fi
-
- echo $foo
- if [ -e "$foo" ] ; then
- latR=$(echo "$1" | awk '{if ($1 < 0) print "S"; else print "N"}')
- lonR=$(echo "$2" | awk '{if ($1 < 0) print "W"; else print "E"}')
- lat=$(echo "$1" | awk '{val = $1; if ($1 < 0) sub(/-/, "", val); print val}') # absolute value
- lon=$(echo "$2" | awk '{val = $1; if ($1 < 0) sub(/-/, "", val); print val}') # absolute value
- # use the following syntax for easy googlian paste of ll=-1.23456,53.345345
- #lonR=$(echo "$2" | awk '{if ($2 < 0) print "W"; else print "E"}')
- echo $lat, $latR, $lon, $lonR, $3, $4, $foo
- function setgpsinfo ()
- {
- exiftool -c "%.6f" -GPSMapDatum="WGS-84" -GPSAltitude=$5 \
- -GPSLongitudeRef=$4 -GPSLongitude=$3 -GPSLatitudeRef=$2 -GPSLatitude=$1 "$6"
- exiftool -GPS:ALL "$6"
- }
-
- if [ -d "$foo" ] ; then
-
- for i in "$foo" ; do # the selection of files treated depend on the passed regex
- echo "i= "$i
- setgpsinfo $lat $latR $lon $lonR $alt "$i"
- done
- else
- setgpsinfo $lat $latR $lon $lonR $alt "$foo"
- fi
- else echo "file or folder is wrong"
- fi
-fi
-</programlisting>
-</sect2>
-</sect1>
-
+ <itemizedlist>
+ <listitem><para>
+ The <guilabel>Undo/Redo</guilabel> tab.
+ </para></listitem>
+ <listitem><para>
+ The <guilabel>Reverse Geocoding</guilabel> tab which allows to find geographic names (cities, street names, ...) by using a public reverse geocoding service and the GPS data of an image.
+ </para></listitem>
+ <listitem><para>
+ The <guilabel>Search</guilabel> tab which allows to find positions on the map from geographic names (cities, monuments, ...) by using a public geoname service (GeoNames and OpenStreetMap at the time of writing).
+ </para></listitem>
+ </itemizedlist>
+
+ <sect2 id="geolocation-map"> <title>The map</title>
+
+ <para>
+ For navigating on the map refer to &marble; handbook, Chapter 2. Also for the sky context menu see &marble; documentation.
+ </para>
+
+ <para>
+ Right under the map you find a row of buttons. I shall use the tooltip texts as designations in the following description. From left to right we have
+
+ <itemizedlist>
+ <listitem><para>
+ The Map-settings button opens a small menu which allows you to choose between Google Maps and &marble; and depending on that choice to choose the kind of map you want to use. Furthermore you can select the projection for &marble; (spherical, Mercator, equirectangular) and you can display a few additional tools like compass and scale on the map.
+ </para></listitem>
+ <listitem><para>
+ The Zoom-in button.
+ </para></listitem>
+ <listitem><para>
+ The Zoom-out button.
+ </para></listitem>
+ <listitem><para>
+ The Switch-between-markers-and-thumbnails button lets you choose whether you want the positions of your images indicated by a marker symbol or by a thumbnail on the map. If you choose thumbnails the next two buttons are of particular interest.
+ </para></listitem>
+ <listitem><para>
+ The Increase-the-thumbnail-size-on-the-map button is doing just that and ...
+ </para></listitem>
+ <listitem><para>
+ ... the Decrease-the-thumbnail-size-on-the-map button as well.
+ </para></listitem>
+ <listitem><para>
+ The Pan-mode button lets you move the map by left-click and holding on it and then drag it with the mouse to where you need it. The cursor symbol will change to a hand.
+ </para></listitem>
+ <listitem><para>
+ The Zoom-into-a-group button is useful if you have images so close to each other on the map that all but the topmost are obscured. Once you click on the visible image the zoom factor will be adjusted so that all the other images behind it become visible. If you click on a group of images and nothing really happens they either have exactly the same geographic position and/or the zoom factor is already at its maximum.
+ </para></listitem>
+ <listitem><para>
+ The Select-images button toggles the selection of an image in the list of images right below the buttons once you click on it on the map. The selection status of all other images in the list remain unchanged.
+ </para></listitem>
+ <listitem><para>
+ The Display-bookmarked-positions-on-the-map button is not working at the time of writing because the whole bookmark issue needs to be reorganized. This also affects the
+ <menuchoice><guimenu>Bookmarks</guimenu>
+ <guimenuitem>Edit Bookmarks...</guimenuitem></menuchoice>
+ item in the context menu on the list of images below the map and the
+ <guilabel>Add Bookmark</guilabel> item in the context menu on the map.
+ </para></listitem>
+ </itemizedlist>
+
+ <anchor id="bookmarkstatus.anchor"/>
+
+ <warning>
+ <para>
+ The use of <guilabel>Add Bookmark</guilabel> in the context menu on the map can lead to loss of your bookmarks in &marble;!
+ </para>
+ </warning>
+
+ </para>
+
+ <para>
+ From the context menu on the map only <guilabel>Copy Coordinates</guilabel> is of interest for geotagging. It copies the geographic coordinates at the cursor position to the clipboard. For all other menu items see &marble; handbook.
+ </para>
+
+ <para>
+ Note that you can change the layout from one map to two maps, beside each other or stacked via the little drop-down menu at the bottom of the Geolocation Editor.
+ </para>
+
+ </sect2>
+
+ <sect2 id="geolocation-edit-coordinates"> <title>Edit Coordinates</title>
+ <para>
+ The coordinates can be set manually in the <guilabel>Details</guilabel> tab (see sreenshot above). The location can be found and fixed iteratively with the displayed map. Move mouse cursor to the region of interest, zoom in, adjust location, zoom in again, and so on until sufficient accuracy is achieved. Note that the zoom center will always be at the cursor position. Eventually you right click at the desired position and choose <guilabel>Copy Coordinates</guilabel>. Now you can go to the list of images below the map, select one or more images, right-click on them and choose <guilabel>Paste Coordinates</guilabel>. The coordinates will then be displayed in the Latitude and Longitude fields to the right of the map. To save your changes you click the <guilabel>Apply</guilabel> button.
+ </para>
+
+ <para>
+ If you have one or more images that already have GPS data you can copy the coordinates from one of those and paste them to one or more other images by using the respective items from the context menu on the list of images. This comes in handy if there is a series of photos taken at the same location.
+ </para>
+
+ <para>
+ To the right of the map there are beside latitude and longitude fields for altitude, speed, number of satellites, fix type and uncertainty (DOP). You may see these fields already filled in if you select a photograph where your camera wrote these information into the EXIF data. Otherwise you can fill them in manually if you have these data from somewhere else, ⪚ a separate GPS receiver. Only for <guilabel>Altitude</guilabel> the context menu on the list of images offers <guilabel>Look up missing altitude values</guilabel> which causes the editor to look up these data in the map data provided the position (latitude and longitude) is already assigned to the photograph.
+ </para>
+
+ <para>
+ Other than that the context menu on the list of images offer items to remove some of the data from the image. Regarding the last item <guilabel>Bookmarks</guilabel> see <link linkend="bookmarkstatus.anchor">here</link>.
+ </para>
+
+ </sect2>
+
+
+ <sect2 id="geolocation-correlator"> <title>The correlator</title>
+ <para>
+ In order to correlate your images with geographic data you need to
+ have a GPS tracking information available as a XML file in <literal>gpx</literal>
+ format (<application><ulink url="http://www.gpsbabel.org">gpsbabel</ulink></application>
+ and <application><ulink url="http://www.ncc.up.pt/gpsman/">gpsman</ulink></application>
+ can download and convert tracking data from a GPS device for you).
+ </para>
+
+ <para>
+ <menuchoice><guimenu>Image</guimenu>
+ <guimenuitem>Geolocation</guimenuitem>
+ <guimenuitem>Correlator</guimenuitem></menuchoice>.
+ This interface can correlate a previously selected number of pictures
+ with registered GPS tracking information.
+ </para>
+
+ <example id="geolocation-geo-correlation-dialog">
+ <title>The geo-correlation dialog based on EXIF date/time and tracking data (gpx format)</title>
+ <screenshot><mediaobject><imageobject><imagedata fileref="tool-geolocation-correlate1.png" format="PNG" /> </imageobject></mediaobject></screenshot>
+ </example>
+
+ <para>
+ Select the images you want to correlate in the application main view, then call the menu. The above dialog will show up. To indicate possible time/location correlation you have to load a track file with <guilabel>Load GPX File</guilabel> that contains GPS data taken at the same time and location as the pictures with your camera.
+ </para>
+
+ <para>
+ When the file is loaded, an automatic correlation is done showing the attributed coordinates in red. GPS track data is invariably recorded
+ in GMT time, so you need to match the camera time with GMT, which
+ can be done with <guilabel>Time Zone</guilabel>. Select the
+ <emphasis>camera time zone</emphasis> here!
+ </para>
+ <para>
+ The <guilabel>Max. time gap</guilabel> setting specifies the limit
+ within which GPS time and camera time shall be deemed coincident.
+ The maximum value is 2000 seconds.
+ </para>
+ <tip><para>If you have no tracking data for pictures that were taken
+ in the same place you can just manually edit a <literal>gpx</literal>
+ file and apply it to those images. The 2000 second time gap will then
+ correlate all pictures taken within 20 minutes.
+ </para></tip>
+
+ <para>
+ The option <guilabel>Interpolate</guilabel> and <guilabel>Difference
+ in min.</guilabel> can be used if there is no match of data. If you
+ know that in reality there is a location match despite a larger time gap
+ between camera and GPS, you can set this limit here and click on the
+ <guilabel>Correlate</guilabel> button to interpolate.
+ </para>
+ <example id="geolocation-correlation">
+ <title>Correlation</title>
+ <screenshot><mediaobject><imageobject><imagedata fileref="tool-geolocation-correlate2.png" format="PNG" /> </imageobject></mediaobject></screenshot>
+ </example>
+ <para>
+ 240 minutes is the maximum time difference that can be introduced here.
+ </para>
+
+ </sect2>
+ </sect1>
</chapter>
<!--
diff --git a/digikam/using-sidebar-maps.docbook b/digikam/using-sidebar-maps.docbook
index ff176fe..7a38503 100644
--- a/digikam/using-sidebar-maps.docbook
+++ b/digikam/using-sidebar-maps.docbook
@@ -4,7 +4,9 @@
&digikam; offers three geolocation tools:
</para>
<orderedlist numeration="arabic">
- <listitem><para>The Map View on the Left Sidebar which is the search tool for finding images by their GPS data.</para></listitem>
+ <!-- <listitem><para>The <link linkend="using-mainwindow-mapview">Map View</link> -->
+ <listitem><para>The Map View
+ on the Left Sidebar which is the search tool for finding images by their GPS data.</para></listitem>
<listitem><para>The <link linkend="tool-geolocationeditor">Geolocation Editor</link> which is accessible via <menuchoice><shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>G</keycap></keycombo></shortcut><guimenu>Item</guimenu><guimenuitem>Edit Geolocation...</guimenuitem></menuchoice> and allows to set and to edit GPS data.</para></listitem>
<listitem><para>This tab on the Right Sidebar which shows the location of the image on a map and is purely informative.</para></listitem>
</orderedlist>
More information about the kde-doc-english
mailing list