<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

  <!ENTITY dhfirstname "<firstname>Stefano</firstname>">
  <!ENTITY dhsurname   "<surname>Zacchiroli</surname>">
  <!ENTITY dhdate      "<date>24 Oct 2019</date>">
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>zack@debian.org</email>">
  <!ENTITY dhusername  "Stefano Zacchiroli">
  <!ENTITY dhucpackage "<refentrytitle>GPSCORRELATE</refentrytitle>">
  <!ENTITY dhpackage   "gpscorrelate">
  <!ENTITY dhversion   "<refmiscinfo class='version'>&dhpackage; @PACKAGE_VERSION@</refmiscinfo>">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;, Till Maas
    </author>
    <copyright>
      <year>2006-2019</year>
      <holder>&dhusername; &dhemail;, Till Maas, Dan Fandrich</holder>
    </copyright>
    <version>
      &dhversion;
    </version>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;

    &dhversion;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>
    <refpurpose>correlates digital images with GPS data filling EXIF fields</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>
      <group>
        <arg choice="plain">-z</arg>
        <arg choice="plain">
          --timeadd +/-<replaceable>HH</replaceable>[:<replaceable>MM</replaceable>]
        </arg>
      </group>
      
      <group>
        <arg choice="plain">-O</arg>
        <arg choice="plain">
          --photooffset <replaceable>seconds</replaceable>
        </arg>
      </group>
      
      <group>
        <arg choice="plain">-i</arg>
        <arg choice="plain">--no-interpolation</arg>
      </group>

      <group>
        <arg choice="plain">-v</arg>
        <arg choice="plain">--verbose</arg>
      </group>

      <group>
        <arg choice="plain">-d</arg>
        <arg choice="plain">--datum <replaceable>datum</replaceable>
        </arg>
      </group>
      
      <group>
        <arg choice="plain">-n</arg>
        <arg choice="plain">--no-write</arg>
      </group>

      <group>
        <arg choice="plain">-R</arg>
        <arg choice="plain">--replace</arg>
      </group>

      <group>
        <arg choice="plain">-m</arg>
        <arg choice="plain">--max-dist <replaceable>time</replaceable>
        </arg>
      </group>

      <group>
        <arg choice="plain">-t</arg>
        <arg choice="plain">--ignore-tracksegs</arg>
      </group>

      <group>
        <arg choice="plain">-M</arg>
        <arg choice="plain">--no-mtime</arg>
      </group>
      
      <group>
        <arg choice="plain">--degmins</arg>
      </group>

      
      <group>
        <arg choice="plain">
          -g <replaceable>file.gpx</replaceable>
        </arg>

        <arg choice="plain">
          <group>
            <arg choice="plain">-l</arg>
            <arg choice="plain">--latlong</arg>
          </group>
          <replaceable>latitude,longitude<group><arg choice="plain">,elevation</arg></group></replaceable>
        </arg>
      </group>

      <arg rep="repeat" choice="plain">
        <replaceable>image.jpg</replaceable>
      </arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>&dhpackage;</command>
      <group choice="plain">
        <arg choice="plain">-s</arg>
        <arg choice="plain">--show</arg>
        <arg choice="plain">-o</arg>
        <arg choice="plain">--machine</arg>
      </group>
      <arg rep="repeat" choice="plain"><replaceable>image.jpg</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>&dhpackage;</command>
      <group choice="req">
        <arg choice="plain">-r</arg>
        <arg choice="plain">--remove</arg>
      </group>

      <group>
        <arg choice="plain">-M</arg>
        <arg choice="plain">--no-mtime</arg>
      </group>
      <arg rep="repeat" choice="plain"><replaceable>image.jpg</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>&dhpackage;</command>
      <group choice="req">
        <arg choice="plain">-f</arg>
        <arg choice="plain">--fix-datestamps</arg>
      </group>

      <group choice="req">
        <arg choice="plain">-z</arg>
        <arg choice="plain">
          --timeadd +/-<replaceable>HH</replaceable>[:<replaceable>MM</replaceable>]
        </arg>
      </group>

      <arg rep="repeat" choice="plain"><replaceable>image.jpg</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>&dhpackage;</command>
      <group choice="plain">
        <arg choice="plain">-V</arg>
        <arg choice="plain">--version</arg>
        <arg choice="plain">-h</arg>
        <arg choice="plain">--help</arg>
      </group>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>This manual page documents the <command>&dhpackage;</command>
    command.
    There is extended documentation available in HTML format; see below.</para>

    <para><command>&dhpackage;</command> is a program that acts on digital images
      in JPEG format, filling in the EXIF (Exchangeable Image File Format) fields
      related to GPS (Global Positioning System) information.  Source for the
      GPS data is a GPX (GPS Exchange Format) file, which records GPS location
      information in an XML-based format. The act of filling those fields is
      referred to as <emphasis>correlation</emphasis>.</para>

    <para> If GPS data are available at the precise moment the image was taken
      (with a 1-second granularity) the GPS data are stored unmodified in EXIF
      fields. If they are not, linear interpolation of GPS data available at
      moments before and after the image was taken can be used.  A measure of
      the approximate accuracy of the GPS location reading is preserved when
      written into the image.</para>

  </refsect1>
  <refsect1>
    <title>OPTIONS</title>

    <para>These programs follow the usual &gnu; command line syntax, with long
      options starting with two dashes (`-').  A summary of options is included
      below.</para>

    <variablelist>
      <varlistentry>
        <term>
          <option>-g</option>,
          <option>--gps</option>
          <replaceable>file.gpx</replaceable>
        </term>
        <listitem>
          <para>Correlate images using the specified GPX file containing
          GPS track points.  This option can be given many times to
          specify multiple GPX files.  For each photo being correlated,
          the first file containing a track covering the time the photo
          was taken will be the one used. All
          <userinput>&lt;trk&gt;</userinput> segments in each file are
          used. </para>
        </listitem>
    </varlistentry>

      <varlistentry>
        <term>
          <option>-l</option>,
          <option>--latlong</option>
          <replaceable>latitude,longitude[,elevation]</replaceable>
        </term>
        <listitem>
          <para>Provide a specific geographic coordinate to use for all images
            instead correlating along a path in a GPX file. The format must be
            of the general form
            <userinput>latitude,longitude,elevation</userinput> where latitude
            and longitude must each be in either decimal form, such as
            <userinput>-123.45678</userinput> or in degrees/minutes/seconds
            form, such as <userinput>-123°45'67.8"</userinput> or
            <userinput>-123d45m67s</userinput>. Providing an elevation is
            optional. Each component can be separated by commas, spaces or tabs.
          </para>
          <para>Note that this option has a known bug in that it does not parse
            numbers correctly in locales that use other than "." as a decimal
            separator.
          </para>
        </listitem>
    </varlistentry>

      <varlistentry>
        <term>
          <option>-s</option>,
          <option>--show</option>
        </term>
        <listitem>
          <para>Only show the GPS data already in the given image's EXIF tags
          instead of correlating them.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-o</option>,
          <option>--machine</option>
        </term>
        <listitem>
          <para>Only show the GPS data of the given images in a
          machine-readable CSV format. Images without GPS tags are
          ignored. The fields output are file name, date and time, latitude,
          longitude, elevation, where the first value is the filename, as
          passed, the second is the timestamp, and the last three are floating
          point values with an optional leading plus or minus.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-r</option>,
          <option>--remove</option>
        </term>
        <listitem>
            <para>Remove all GPS EXIF data from the given images.  Note that
            this only removes the GPS tags that the program could add; it
            does not delete all possible GPS EXIF tags. All other tags are
            left alone.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-z</option>,
          <option>--timeadd</option>
          <userinput>+/-</userinput><replaceable>HH</replaceable>[<userinput>:</userinput><replaceable>MM</replaceable>]
        </term>
        <listitem>
          <para>Time to add to GPS points to make them match the timestamps of the
            images. GPS timestamps are in UTC; image timestamps are generally
            in local time.  Enter the timezone used when taking the images; e.g.,
            <userinput>+8</userinput> for Perth, Western Australia or
            <userinput>-2:30</userinput> for St. John's, Newfoundland.
            This defaults to the UTC offset of the local time zone as of the
            time of the first image processed (versions before 1.7 defaulted to
            00:00). </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>
          <option>-O</option>,
          <option>--photooffset</option>
          <replaceable>seconds</replaceable>
        </term>
        <listitem>
          <para>Time in seconds to add to the photo timestamp to make it match
          the GPS timestamp.  To determine the number of seconds needed, just
          create a photograph of your GPS device showing the current time and
          compare it with the timestamp of your photo file. The EXIF time
          tags in the image are not modified based on this value.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-i</option>,
          <option>--no-interpolation</option>
        </term>
        <listitem>
          <para>Disable linear interpolation between points.
          With this flag, the nearest exact point (within
          <userinput>--max-dist</userinput>) is used. Without this flag,
          photos taken between the time of two recorded GPS coordinates
          are correlated based on linear interpolation between those two
          points. </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-v</option>,
          <option>--verbose</option>
        </term>
        <listitem>
          <para>Show slightly more information during the image
          correlation process, such as the GPS data selected for each
          image.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-d</option>,
          <option>--datum</option> <replaceable>datum</replaceable>
        </term>
        <listitem>
          <para>Specify GPS measurement datum. If not
          set, <userinput>WGS-84</userinput> is used
          (<userinput>TOKYO</userinput> is another possibility).  However, GPX
          is not supposed to store anything but WGS-84, so this should only
          ever be needed with the <userinput>--latlong</userinput>
          option.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-n</option>,
          <option>--no-write</option>
        </term>
        <listitem>
          <para>Do not write the correlated EXIF data back into the
          image. Useful with <userinput>--verbose</userinput> to see
          what would happen during image correlation.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-R</option>,
          <option>--replace</option>
        </term>
        <listitem>
          <para>Overwrite any existing GPS tags in the file.
          Without this option, any file that already contains GPS tags will
          be skipped.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-m</option>,
          <option>--max-dist</option> <replaceable>time</replaceable>
        </term>
        <listitem>
          <para>Maximum time in seconds from the photo time which a
          logged GPS point can refer and still be used for
          correlation.  This defaults to 0, which means to disable this
	  check. Only one of the two points need be within this range
	  for correlation to take place.</para>
          <para> If the accuracy of the location is paramount and you
          would rather not correlate a position for a photo at all if
          the nearest GPS coordinates were recorded too long ago in the
          past or too far into the future (relative to when the photo
          was taken), then set this to a nonzero value.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-t</option>,
          <option>--ignore-tracksegs</option>
        </term>
        <listitem>
          <para>Interpolate between track segments, too.
          Generally, track segments show multiple sessions of GPS logging;
          between them is generally when the GPS was not logging.
          Since interpolation honours the <userinput>--max-dist</userinput>
          flag, even track segments with wide time gaps can
          safely be used if both flags are set.  Without this
          flag, photos taken within the time gap between two
          <userinput>&lt;trkseg&gt;</userinput> tracks in the GPX file
          are not correlated.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-M</option>,
          <option>--no-mtime</option>
        </term>
        <listitem>
          <para>Do not change the last modification time of changed
          files.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-f</option>,
          <option>--fix-datestamps</option>
        </term>
        <listitem>
          <para>Fix broken GPS datestamps written with
          <command>gpscorrelate</command> versions &lt; 1.5.2 by replacing
          them with the photo's time stamp.  Prior to 1.5.2,  two bugs
          wrote the wrong value for the GPSDateStamp and GPSTimeStamp tags.
          This option will check each supplied filename for the problem and
          correct it. Use with <userinput>--no-write</userinput> to prevent
          writing these changes (useful for checking for the issue).  This
          option also implies <userinput>--no-mtime</userinput>. You will
          also need to use <userinput>--timeadd</userinput> to specify the
          difference between localtime and UTC time for the supplied
          photos.</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>
          <option>--degmins</option>
        </term>
        <listitem>
          <para>Write location as DD MM.MM (instead of the more accurate DD MM
          SS.SS) as was the default in <command>gpscorrelate</command>
          versions &lt; 1.5.3. There is no good reason to use this option
          unless some broken program expects this style.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-h</option>,
          <option>--help</option>
        </term>
        <listitem>
          <para>Only show a summary of options.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-V</option>,
          <option>--version</option>
        </term>
        <listitem>
          <para>Only print the <command>gpscorrelate</command> version number
	  and copyright information.</para>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>
  <refsect1>
    <title>EXAMPLES</title>

    <para>
    To correlate all photos in a directory taken in western Europe in the
    summer (i.e., UTC-2):</para>
    <para>
    <userinput>gpscorrelate -g Test.gpx -z 2 *.jpg</userinput>
    </para>

    <para>
    To correlate all photos in a directory taken in Italy, switching to UTC-2
    or UTC-1 depending on the daylight savings time in effect when the first
    picture in the list was taken:</para>
    <para>
    <userinput>env TZ=Europe/Rome gpscorrelate -g Test.gpx *.jpg</userinput>
    </para>

    <para>
    Correlate all photos in a directory from a track spread out over two
    different track files and taken in the computer's current time zone,
    interpolating between segments and between files while ignoring photos
    taken too far away from a recorded point, without changing the file time
    stamp of the files, while showing details of the process:</para>
    <para>
    <userinput>gpscorrelate -g track1.gpx -g track2.gpx -m 120 -t -M -v *.jpg</userinput>
    </para>

    <para>
    To correlate a photo taken from a camera with a fast clock (i.e., the clock
    was 77 seconds ahead of GPS time):
    </para>
    <para>
    <userinput>gpscorrelate -g Test.gpx -O -77 photo.jpg</userinput>
    </para>

    <para>
    Show existing GPS tags in a photo:
    </para>
    <para>
    <userinput>gpscorrelate --show photo.jpg</userinput>
    </para>

    <para>
    Show existing GPS tags in a photo and output in CSV format:
    </para>
    <para>
    <userinput>gpscorrelate --show --machine photo.jpg</userinput>
    </para>

    <para>
    Remove GPS tags from photos:
    </para>
    <para>
    <userinput>gpscorrelate --remove *.jpg</userinput>
    </para>

    <para>
    Add a GPS location tag to a photo taken at Ulmer Münster:</para>
    <para>
    <userinput>gpscorrelate -l 48.398620,9.991417,522 -z 2 ulm.jpg</userinput>
    </para>
  </refsect1>
  <refsect1>
    <title>EXIT STATUS</title>

    <para>
	    <command>gpscorrelate</command> returns <errorcode>0</errorcode> in
	    case of success, <errorcode>1</errorcode> in case of major error
	    (such as a read or write error) and <errorcode>2</errorcode> in
	    case of minor error (such as the given GPS track not covering the
	    time of an image).
    </para>

  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>

    <para><citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	  <citerefentry><refentrytitle>gpsbabel</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	  <citerefentry><refentrytitle>gpxlogger</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	  <citerefentry><refentrytitle>cgpxlogger</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
    </para>

    <para>The documentation of &dhpackage; in HTML format is available on the
    filesystem at <filename class="directory">@DOCDIR@</filename>.
    </para>

  </refsect1>
  <refsect1>
    <title>LICENSE</title>

    <para>This manual page was initially written by &dhusername; &dhemail; for
    the &debian; system.  It was extended by Till Maas
    <email>opensource@till.name</email> and Dan Fandrich
    <email>dan@coneharvesters.com</email>. Permission is granted to
    copy, distribute and/or modify this document under the terms of
    the &gnu; General Public License, Version 2 or any later version
    published by the Free Software Foundation. </para>

  </refsect1>
</refentry>

