<chapter id="tool-geolocation">
<chapterinfo>

    <abstract>
        <para>
            Geolocation means assigning, editing and using metadata which describe the geographic place where images or videos were taken. The source of these metadata can be your camera, a separate GPS receiver or other means of geographical information, in particular maps.
        </para>

        <para>
            Not only for professional photographers can it be interesting to link an image to a precise geographical location. Not everybody uses an airplane to overfly and scan a certain area with automatic GPS data recording. Environmental planners, military, police, construction bureaus, real estate agencies, all will have an immediate application.
        </para>

        <para>
            But if, after some time, one has forgotten where the image was taken, if one loves the nice feature to open with a simple click a browser displaying a zoom of the area, if you like to send your image as a postcard to another &digikam; user (who is then able to locate your shot), or if you simply need the documentation aspect of it - having position data stored in a photo is great.
        </para>

    </abstract>

    <keywordset>
        <keyword>GPS</keyword>
        <keyword>Map</keyword>
    </keywordset>
</chapterinfo>

<title>Geolocation</title>
    <para>
        GPS (global positioning system) is used as a generic term throughout this document. It just means a location in the common spherical coordinate system that can be displayed on a map. The actual technical implementation that provides the data can be the American GPS, the Russian GLONAS, the European GALILEO or any other system.
    </para>

    <para>
        There are four tools regarding geolocation in &digikam-app; and two in &showfoto;:
    </para>
        <orderedlist numeration="arabic">

            <listitem><para>
                The Map mode of the Image Area which displays images with GPS data on a map depending on the selection on the Left Sidebar, &eg; the images in the album you selected in the Album View, the images with a certain tag assigned (selected in the Tag View), with a certain label and so on. This is only available in &digikam-app;.
            </para></listitem>
    
            <listitem><para>
                The Map View on the Left Sidebar of &digikam-app; which is the search tool for finding images by their GPS data. This is also only available in &digikam-app;.
            </para></listitem>

            <listitem><para>
                The Geolocation Editor we describe a little bit further below 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> (<menuchoice><guimenu>File</guimenu><guimenuitem>Edit Geolocation...</guimenuitem></menuchoice> in &showfoto;).
            </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>
    <para>
        All four 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>

    <sect1 id="tool-geolocationeditor">  <title>Geolocation Editor</title>
    
        <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 Geocoding</firstterm> tool.
        </para>

        <para>
            <inlinemediaobject>
                <imageobject><imagedata fileref="&path;tool-geolocation-editcoords.png" format="PNG" /></imageobject>
            </inlinemediaobject>
        </para>

        <para>
            The Geolocation Editor provides the tools to localize pictures geographically in the common spherical coordinate system (used by GPS/Galileo). Altitude, latitude and longitude, speed, number of satellites, fix type and DOP are editable.
        </para>
       
        <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>
            Furthermore the Right Sidebar offers three more tools:
        </para>
        
        <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 click with the &LMB; 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>
                        <para>
                            Note that <quote>group</quote> in this context here has nothing to do with grouped images as described in chapter 2 of the &digikam-app; Handbook. Here the term refers to images which are very close to each other on the map (depending on the zoom factor) or have exactly the same geographic position.
                        </para>
                    </listitem>
                    <listitem><para>
                        The Select-images button toggles the selection of an image or a group of images 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. Be aware of the fact that there is a kind of two-stage selection! If you click on a thumbnail or marker on the map the selected image(s) in the list of images will become a light blue background. If you click on it in the list the background will become a darker blue and if there where more than one image with light blue background before the others will become un-selected. Only clicking on an image in the list will let its preview appear to the right of the list.
                    </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 or above each other 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 screenshot above). The location can be found and fixed iteratively with the displayed map. Move the 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 click with the &RMB; 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, click with the &RMB; 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 right under the <guilabel>DOP</guilabel> field.
            </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, &eg; a separate GPS receiver. Note that you have to check the relevant checkbox before you can edit a field (under &Windows; you may have to double-click it). 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>
                To delete geolocation data you got to un-check the relevant checkbox and click the <guilabel>Apply</guilabel> button right under the <guilabel>DOP</guilabel> field. 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://gpsman.sourceforge.net/">gpsman</ulink></application>
                can download and convert tracking data from a GPS device for you). The idea is: while taking your pictures just keep a GPS device running and carry it around with the camera. Once you are done, download the pictures and the GPS tracks, and run the correlator.
            </para>

            <para>
                <inlinemediaobject>
                    <imageobject><imagedata fileref="&path;tool-geolocation-correlate1.png" format="PNG" /></imageobject>
                </inlinemediaobject>
            </para>

            <para>
                Select the images you want to correlate in the application main view, then call the geolocation editor with <menuchoice><shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>G</keycap></keycombo></shortcut><guimenuitem> </guimenuitem></menuchoice> and switch to the <guilabel>GPS Correlator</guilabel> tab on the Right Sidebar. The above dialog will show up with the selected images in the list below the map. 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.
            </para>

            <para>
                When the file is loaded and <guilabel>Show tracks on map</guilabel> is checked the track is displayed on the map. You can load more than one file and &digikam; will assign different colors to them and display the tracks on the map accordingly.
            </para>

            <para>
                GPS track data is invariably recorded in UTC (Universal Time Coordinated), so you need to match the camera time with UTC, which can be done with <guilabel>Camera time zone:</guilabel>. Select <guilabel>Same as system</guilabel> if you took the photographs in your home time zone and &digikam; will figure out the difference to UTC from your system time. If you took the photographs somewhere else you got to check <guilabel>Manual:</guilabel> and choose the appropriate difference from the drop-down field to the right. You can use the same mechanism as well to correct a simple mis-adjustment of your camera time for whatever reasons or an offset of a gpx-file due to quirks of a software used to convert other track file formats into gpx. Here comes <guilabel>Fine offset (mm:ss)</guilabel> into play where you can add or subtract up to 59 minutes and 59 seconds to your time difference chosen in the field above.
            </para>

            <para>
                The <guilabel>Max. time gap (sec.):</guilabel> setting specifies the limit within which GPS time and camera time shall be deemed coincident. The maximum value is 2000 seconds. This means that if no entry in the gpx-file matches the time stamp of the photograph exactly, the position of the entry with the smallest time gap to the photograph will become assigned to it as long as this time gap is smaller than the <guilabel>Max. time gap (sec.):</guilabel> setting. If you wonder which value you should specify here a look into the settings of your track recording device/software or into the gpx-file (which is easily possible with a text editor) might help. The faster you were moving while taking the photograph(s) the more important this decision will be.
            </para>

            <para>
                <guilabel>Interpolate</guilabel> offers another option in case there is no exact match between the time stamp of your photograph(s) and an entry in the gpx-file and as long as you were moving more or less straight between two recorded GPS positions it will be the more precise option. Here the position of the photograph is calculated (linear interpolated) from the positions of the two closest entries in the gpx-file and the respective differences in time. If, for instance, the time gaps between the two closest entries and the photograph are equal the position assigned will be on a straight line between the positions of the two entries right in the middle.
            </para>
            
            <para>
                <guilabel>Max. interpol. time gap (min):</guilabel> has nothing to do with policeman Max from Interpol ;-) Instead it determines whether a GPS point is eligible for interpolation. If its time is farther away from the picture time than this limit, it cannot be used. 240 minutes is the maximum time difference that can be introduced here.
            </para>
            
            <para>
                 Once your settings are done you click on the <guilabel>Correlate</guilabel> button. If there is no match at all you will get the message "Could not correlate any image - please make sure the timezone and gap settings are correct." Otherwise you will get something like "2 out of 4 images have been correlated. Please check the timezone and gap settings if you think that more images should have been correlated." Best case you get "All images have been correlated. You can now check their position on the map."
            </para>
            
            <para>
                If you want to follow this recommendation it is a good idea to change to the <guilabel>Details</guilabel> tab since there you have a preview of the images which can help a lot to identify them on the map. Remember that you always have to click on an image in the list under the map to make its preview show up. Once you are satisfied with the results click the <guilabel>Apply</guilabel> button at the bottom of the Geolocation Editor to save the changes to the image file and the database.
            </para>

        </sect2>
        
        <sect2 id="geolocation-undo-redo">       <title>Undo/Redo</title>
            <para>
                In the <guilabel>Undo/Redo</guilabel> tab a history is being recorded about all the changes you apply to the images loaded into the Geolocation Editor. The history shows changes made in only one tab or in several tabs and will be deleted only once you leave the editor. After a few actions in the different tabs the record might look like this:
            </para>
            
            <para>
                <inlinemediaobject>
                    <imageobject><imagedata fileref="&path;tool-geolocation-undo1.png" format="PNG" /></imageobject>
                </inlinemediaobject>
            </para>
                
            <para>
                The last step is highlighted when you enter the tab. The first step is always labeled <quote>empty</quote> and represents the status the images had when they were loaded. You can click on every step and, depending on what kind of changes you did, you might see the images appearing, disappearing or moving on the map or see the differences in the list of images under the map. Note that the list is configurable by clicking with the &RMB; on the header.
            </para>
            
            <para>
                Now let's assume that you realize that the move in the last step was wrong. You just click on the step before (Details changed), you go to the <guilabel>Search</guilabel> tab (described further below) and you do another move. After returning to the <guilabel>Undo/Redo</guilabel> tab it might look like this:
            </para>
            
            <para>
                <inlinemediaobject>
                    <imageobject><imagedata fileref="&path;tool-geolocation-undo2.png" format="PNG" /></imageobject>
                </inlinemediaobject>
            </para>
        </sect2>
        
        <sect2 id="geolocation-reverse-geocoding">       <title>Reverse Geocoding</title>
            <para>
                In this tab you can use a public geoname service to look up address details of the geographic position of one or more images and convert them into tags. In order to do that you need a few preparations. You should be already familiar with the idea of tags and how to create, edit and use them. The best entry into this issue you find in the Tags View section of Chapter 2 of the &digikam-app; handbook.
            </para>
            <para>
                First you should create a root tag in the Tag Manager or in the tag tree of the Left or Right Sidebar. You might name it Location or Places or ...
            </para>
            <para>
                Then you select the image(s) you want to tag (they need to have GPS data assigned), open the Geolocation Editor and click the <guilabel>Reverse Geocoding</guilabel> tab. You will see your tag tree and if you click with the &RMB; over a tag, preferable the one you created for the geo tags, you will see this context menu:
            </para>
            
            <para>
                <inlinemediaobject>
                    <imageobject><imagedata fileref="&path;tool-geolocation-reverse1.png" format="PNG" /></imageobject>
                </inlinemediaobject>
            </para>

            <para>
                In the main section the tags you can add are sorted from the largest region (country) down to the smallest (house number). If you choose <guilabel>Add all address elements</guilabel> and then fold out the Location tag and all the sub-tags you will have this:
            </para>

            <para>
                <inlinemediaobject>
                    <imageobject><imagedata fileref="&path;tool-geolocation-reverse2.png" format="PNG" /></imageobject>
                </inlinemediaobject>
            </para>

            <para>
                These red tags in curly brackets are called control tags. They determine which address elements you want the reverse geolocation service you have chosen at the top under <guilabel>Select service</guilabel> to look for. You can still delete some of them with the help of the context menu if you feel that you don't need them or modify the structure by deleting some control tags and add them in other places of the tree or even build a new tree parallel to the first by adding a control tag to the root tag (here: Location). Arranging the control tags on the same level instead of a tree structure can save a lot of redundant tags since the same city or town name exists in more than one state or country let alone street names. But it can make the whole location branch of your tag tree quite long and therefore incalculable. This is to say that you have to find your own solution to this problem depending on your needs, maybe a mix, and the sooner you find it the less work you have to invest in editing your tag tree and the control tags.
            </para>
            <para>
                Let us assume you use the control tags as shown in the above screenshot, select the images you want to tag from the list of images to  the left and click <guilabel>Apply reverse geocoding</guilabel>. Then the tag tree might look similar to this:
            </para>
 
            <para>
                <inlinemediaobject>
                    <imageobject><imagedata fileref="&path;tool-geolocation-reverse3.png" format="PNG" /></imageobject>
                </inlinemediaobject>
            </para>
            
            <para>
                The green tags represent the search result of the selected public reverse geocoding service and are already assigned to the image(s). To save these tags to the image file and the &digikam; database click <guilabel>Apply</guilabel>. The tags will appear as regular tags in your tag tree which you can see already here or in the tag tree of the Left or Right Sidebar. Of course you can still edit them like any other tag in the Tag Manager or in the Left or Right Sidebar, but not here in the Geolocation Editor.
            </para>

        </sect2>
        
        <sect2 id="geolocation-search">       <title>Search</title>
            <para>
                In the <guilabel>Search</guilabel> tab you can look up places by their geographic names using public geoname services (GeoNames and OpenStreetMap at the time of writing). You just type in a name of a place (city, monument, hotel, ...) into the input field at the top and click <guilabel>Search</guilabel>. In the result list below you will get something like this:
            </para>
            
            <para>
                <inlinemediaobject>
                    <imageobject><imagedata fileref="tool-geolocation-search.png" format="PNG" /></imageobject>
                </inlinemediaobject>
            </para>
            
            <para>
                Obviously Paris does not only exist in France. So if you were looking for the capital of France you can either scroll down the list until you find an entry that undoubtedly belongs to there like "Arc de Triomphe" and click on it or specify your search a little bit more precise like "Paris, Arc de Triomphe" or "Paris, France". Once you click on an entry in the list the map will become centered to that place and you can now zoom in with the zoom-in button (second from the left below the map). Using this example with GeoNames you will notice that you still get a lot of results and even two labeled only "Arc de Triomphe", the second one a street a few hundred meters away from the arch. With OSM you get only one result. You got to play a bit with the different services in different regions, with more or less precise search terms and then you will get an idea about how to best conduct your searches.
            </para>
            <para>
                For the buttons right above the result list refer to their tooltips! The context menu on search result entries offers
            </para>
            
            <itemizedlist>
                <listitem><para><guilabel>Copy coordinates</guilabel> which you can paste later to one or more images in the image list under the map</para></listitem>
                <listitem><para><guilabel>Move selected images to this position</guilabel> which is basically the same but more straightforward provided you have the images already loaded into the geolocation editor</para></listitem>
                <listitem><para><guilabel>Remove from results list</guilabel> which is particular useful in conjunction with the Keep-the-results-of-old-searches-... button above the results list.</para></listitem>
            </itemizedlist>

        </sect2>
    </sect1>
</chapter>

<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
