<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
                <!ENTITY % darktable_dtd SYSTEM "../dtd/darktable.dtd">
                %darktable_dtd;
                ]>
<chapter status="final" id="map_chapter">

  <chapterinfo>
    <keywordset>
      <keyword>geotagging</keyword>
      <keyword>map</keyword>
      <keyword>view</keyword>
    </keywordset>
  </chapterinfo>

  <title>Map</title>

  <indexterm>
    <primary>map view</primary>
  </indexterm>

  <para>
    The Map view is were you geotag your images.
  </para>

  <para>
    <screenshot>

      <screeninfo>The map view</screeninfo>

      <graphic fileref="images/map_view.png" scalefit="1" width="80%"></graphic>

    </screenshot>
  </para>

  <sect1 status="final">

    <title>Overview</title>

    <para>
      Map view will show you a world map with the currently open image, or film roll of images,
      pinned to their geotagged location. This requires that the image was geotagged by a camera
      with that feature. Some newer cameras, including smartphones, are already equipped with
      GPS receivers. Other cameras may need additional GPS hardware to do this.
    </para>

    <para>
      Even if your camera doesn't support this feature, there is an alternative method.
      darktable can match the Exif time and date data in your image(s) to a separate GPX data
      tracking file created by a GPS tracker recording your movements. These can be handheld
      devices or a GPS tracker app on your smartphone. This is all done in the lighttable view
      (see <xref linkend="geotagging"/>).
    </para>

    <sect2 status="final">

      <title>Center map view</title>

      <informaltable frame="none">
        <tgroup cols="2" colsep="0" rowsep="0">
          <colspec colwidth="6*"/>
          <colspec colwidth='5cm'/>
          <tbody>
            <row>
              <entry>
                In the center of the map view you will see a map.
              </entry>
              <entry>
                <graphic fileref="map/images/map_center_view.png" scalefit="1" width="80%" align="center" />
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <para>
        Map data are taken from open map sources on the internet. New map data are only
        available if you are connected to the internet. darktable keeps a disk cache of
        previously loaded map data.
      </para>

      <para>
        Your mouse will allow navigation in the map. Left-click will drag the map; using the
        scroll-wheel will zoom in or out.
      </para>

      <para>
        There are on-screen controls and displays that assist you to find your way. A navigation
        area is located on top left of the map. Use it as an alternative to mouse-dragging and
        scrolling. The scale of your map is displayed on bottom left. On bottom right you see
        the geographical coordinates for the center of the map.
      </para>

      <para>
        Images that already have geo location attributes in their metadata are displayed as
        small icons on the map.
      </para>

      <para>
        In order to assign geo coordinates to an image, activate the film-strip on the lower
        panel (press <emphasis> Ctrl-f</emphasis>). You can simply assign a geo location to an
        image by dragging the image icon from the film-strip and position it onto the map.
        darktable will record the new geo location (longitude and latitude) as part of the image
        metadata. Exported images will include this data.
      </para>

      <para>
        In order to remove geo coordinates from an image just drag it from the map and drop it
        onto the filmstrip.
      </para>

      <para>
        Left and right to the central map there are panels for additional control.
      </para>

    </sect2>

    <sect2>

      <title>Undo/redo</title>

      <indexterm>
        <primary>undo</primary>
      </indexterm>

      <indexterm>
        <primary>redo</primary>
      </indexterm>

      <para>
        All image moves in the map view are recorded by darktable. It is then possible to undo
        or redo such changes to recover a previous state. Note that this undo/redo facility is
        unlimited while moving images but it is reset each time the map view is left.
      </para>

      <para>
        The default key shortcuts are:
        <itemizedlist>

          <listitem><para>
            <emphasis>Ctrl-z</emphasis> : undo last move
          </para></listitem>

          <listitem><para>
            <emphasis>Ctrl-y</emphasis> : redo last undo (does nothing if undo has not been used
            yet)
          </para></listitem>

        </itemizedlist>
      </para>

    </sect2>

  </sect1>

<!-- Panels -->

  <xi:include href="panels/panels.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

</chapter>