doc/gpst.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>gpst</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.1" /></head><body><div xml:lang="en" class="refentry" title="gpst" lang="en"><a id="gpst"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>gpst — Converts between various GPS formats.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">gpst</code>  [
   4         <em class="replaceable"><code>options</code></em>
   5       ] [
   6         <em class="replaceable"><code>file</code></em>
   7       ...]</p></div><div class="cmdsynopsis"><p><code class="command">gpst</code>  {-S} [
   8         <em class="replaceable"><code>options</code></em>
   9       ] [
  10         <em class="replaceable"><code>file</code></em>
  11       ...]</p></div></div><div class="refsect1" title="Description"><a id="gpst.description"></a><h2>Description</h2><div class="variablelist"><dl><dt><span class="term"><code class="option">--chronology</code></span></dt><dd><p>Check for broken chronology, warn about entries with an
  12           old timestamp.</p></dd><dt><span class="term"><code class="option">-d</code>, <code class="option">--skip-dups</code></span></dt><dd><p>If succeeding identical coordinates are found, print
  13           only the first one and ignore the rest.</p></dd><dt><span class="term"><code class="option">-e</code>, <code class="option">--epoch</code></span></dt><dd><p>Use seconds since 1970-01-01 00:00:00 GMT as date
  14           format.</p></dd><dt><span class="term"><code class="option">--fix</code></span></dt><dd><p>Comment out entries which is obviously wrong.
  15           Use together with <code class="option">--chronology</code> to fix those
  16           kind of errors.
  17           Does not work with GPX output yet.</p></dd><dt><span class="term"><code class="option">--from-date
  18         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Used by the <code class="literal">pgwupd</code> format.
  19           Specifies from which date waypoints should be updated.
  20           No checks for valid date format here, let
  21           <span class="application">PostgreSQL</span> take care of that.
  22           All variants it understands can be used here.</p></dd><dt><span class="term"><code class="option">-h</code>, <code class="option">--help</code></span></dt><dd><p>Send a brief help summary to stdout.</p></dd><dt><span class="term"><code class="option">--inside</code></span></dt><dd><p>Print only trackpoints inside a rectangle specified by
  23           <code class="option">--pos1</code> and <code class="option">--pos2</code>.</p></dd><dt><span class="term"><code class="option">-n</code>, <code class="option">--undefined
  24         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Use <em class="replaceable"><code>x</code></em> as undefined
  25           value.</p></dd><dt><span class="term"><code class="option">--near</code></span></dt><dd><p>Add names of the three closest waypoints to the
  26           trackpoint.
  27           Unfinished and experimental, needs <span class="citerefentry"><span class="refentrytitle">gpsbabel</span>(1)</span>, which is called from
  28           the program as
  29           <span class="command"><strong>/usr/local/bin/gpsbabel</strong></span>.</p></dd><dt><span class="term"><code class="option">-o</code>, <code class="option">--output-format
  30         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Use output format <em class="replaceable"><code>x</code></em>:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">clean</code></span></dt><dd><p>TAB-separated format with longitude, latitude and
  31                 altitude.</p></dd><dt><span class="term"><code class="option">csv</code></span></dt><dd><p>TAB-separated format:
  32                 </p><div class="variablelist"><dl><dt><span class="term">date</span></dt><dd><p>Date of trackpoint.
  33                       Format:
  34                       <code class="literal"><em class="replaceable"><code>yyyy</code></em>-<em class="replaceable"><code>mm</code></em>-<em class="replaceable"><code>dd</code></em>T<em class="replaceable"><code>hh</code></em>:<em class="replaceable"><code>mm</code></em>:<em class="replaceable"><code>ss</code></em>Z</code>
  35                       unless the <code class="option">--epoch</code> option is
  36                       specified.
  37                       If so, it’s represented as number of seconds since
  38                       1970-01-01 00:00:00 UTC.</p></dd><dt><span class="term">longitude</span></dt><dd><p>Longitude, decimal degrees.</p></dd><dt><span class="term">latitude</span></dt><dd><p>Latitude, decimal degrees.</p></dd><dt><span class="term">altitude</span></dt><dd><p>Altitude in metres above sea level.
  39                       Optional.
  40                       If not present, the corresponding TAB is also
  41                       printed, to keep the number of columns
  42                       intact.</p></dd></dl></div></dd><dt><span class="term"><code class="option">gpsml</code> (Default)</span></dt><dd><p>Line-based XML which makes it easy to edit and
  43                 grep.
  44                 In the past, there was this big plan about making this
  45                 the default storage format, so it was declared as The
  46                 Honourable Default Output Format.
  47                 But using GPX is the way to go, so this will probably
  48                 change in the future.
  49                 It’s way too <span class="foreignphrase"><em class="foreignphrase">de facto</em></span> and
  50                 widely used, so storing GPS data in anything else is
  51                 sheer waste of work.
  52                 Probably not finished yet.</p></dd><dt><span class="term"><code class="option">gpstrans</code></span></dt><dd><p>The format generated by <span class="citerefentry"><span class="refentrytitle">gpstrans</span>(1)</span>.</p></dd><dt><span class="term"><code class="option">gpx</code></span></dt><dd><p>Not complete yet, but good enough in most
  53                 cases.</p></dd><dt><span class="term"><code class="option">pgtab</code></span></dt><dd><p>TAB-separated format for import into
  54                 <span class="application">PostgreSQL</span>.
  55                 Undefined values are written as <code class="literal">\N</code> if
  56                 the <code class="option">--undefined</code> option is not
  57                 specified.</p><div class="variablelist"><dl><dt><span class="term"><span class="database">date</span></span></dt><dd><p>Format:
  58                       <code class="literal"><em class="replaceable"><code>yyyy</code></em>-<em class="replaceable"><code>mm</code></em>-<em class="replaceable"><code>dd</code></em>T<em class="replaceable"><code>hh</code></em>:<em class="replaceable"><code>mm</code></em>:<em class="replaceable"><code>ss</code></em>Z</code></p></dd><dt><span class="term"><span class="database">coor</span></span></dt><dd><p>Format:
  59                       <code class="literal">(<em class="replaceable"><code>lat</code></em>,<em class="replaceable"><code>lon</code></em>)</code></p></dd><dt><span class="term"><span class="database">ele</span></span></dt><dd><p>Altitude in metres above sea level.</p></dd><dt><span class="term"><span class="database">name</span></span></dt><dd><p>Short name of closest waypoint.
  60                       Calculated in
  61                       <span class="application">PostgreSQL</span>, so this
  62                       value is always <code class="literal">\N</code>.</p></dd><dt><span class="term"><span class="database">dist</span></span></dt><dd><p>Distance in decimal degrees to closest
  63                       waypoint.
  64                       Calculated in
  65                       <span class="application">PostgreSQL</span>, so this
  66                       value is always <code class="literal">\N</code>.</p></dd><dt><span class="term"><span class="database">description</span></span></dt><dd><p>Description of waypoint.
  67                       Calculated in
  68                       <span class="application">PostgreSQL</span>, so this
  69                       value is always <code class="literal">\N</code>.</p></dd></dl></div></dd><dt><span class="term"><code class="option">pgwtab</code></span></dt><dd><p>Output waypoints on a TAB-separated format:</p><div class="variablelist"><dl><dt><span class="term"><span class="database">coor</span></span></dt><dd><p>Format:
  70                       <code class="literal">(<em class="replaceable"><code>lat</code></em>,<em class="replaceable"><code>lon</code></em>)</code></p></dd><dt><span class="term"><span class="database">name</span></span></dt><dd><p>Title of waypoint.</p></dd><dt><span class="term"><span class="database">ele</span></span></dt><dd><p>Elevation in metres above sea level.</p></dd><dt><span class="term"><span class="database">type</span></span></dt><dd><p>Type of waypoint, same as the GPX <code class="sgmltag-starttag">&lt;type&gt;</code> element.</p></dd><dt><span class="term"><span class="database">time</span></span></dt><dd><p>Timestamp of waypoint.</p></dd><dt><span class="term"><span class="database">cmt</span></span></dt><dd><p>Short waypoint description, used by the GPS
  71                       as a comment.
  72                       Same as the GPX <code class="sgmltag-starttag">&lt;cmt&gt;</code> element.</p></dd><dt><span class="term"><span class="database">descr</span></span></dt><dd><p>Long description, not used by the GPS.
  73                       Same as the GPX <code class="sgmltag-starttag">&lt;desc&gt;</code> element.</p></dd><dt><span class="term"><span class="database">src</span></span></dt><dd><p>Source of data, same as the <code class="sgmltag-starttag">&lt;src&gt;</code> GPX element.</p></dd><dt><span class="term"><span class="database">sym</span></span></dt><dd><p>GPS symbol name.
  74                       Same as the <code class="sgmltag-starttag">&lt;sym&gt;</code> GPX element.</p></dd></dl></div></dd><dt><span class="term"><code class="option">pgwupd</code></span></dt><dd><p>Output waypoints as SQL transactions which updates
  75                 the <span class="database">name</span> and
  76                 <span class="database">dist</span> columns.</p></dd><dt><span class="term"><code class="option">poscount</code></span></dt><dd><p>Creates a 3D plot where areas with many
  77                 trackpoints are higher than areas with less track
  78                 points.</p></dd><dt><span class="term"><code class="option">ps</code></span></dt><dd><p>Postscript. Unfinished.</p></dd><dt><span class="term"><code class="option">svg</code></span></dt><dd><p>Unfinished.</p></dd><dt><span class="term"><code class="option">xgraph</code></span></dt><dd><p>Input format for <span class="citerefentry"><span class="refentrytitle">xgraph</span>(1)</span>.</p></dd><dt><span class="term"><code class="option">ygraph</code></span></dt><dd><p>Input format for <span class="citerefentry"><span class="refentrytitle">ygraph</span>(1)</span>.</p></dd></dl></div></dd><dt><span class="term"><code class="option">--outside</code></span></dt><dd><p>Print only trackpoints outside a rectangle specified by
  79           <code class="option">--pos1</code> and <code class="option">--pos2</code>.</p></dd><dt><span class="term"><code class="option">--pos1
  80         <em class="replaceable"><code>x1</code></em>,<em class="replaceable"><code>y1</code></em></code>, </span><span class="term"><code class="option">--pos2
  81         <em class="replaceable"><code>x2</code></em>,<em class="replaceable"><code>y2</code></em></code></span></dt><dd><p>Specifies corners of an area rectangle used by the
  82           <code class="option">--inside</code> and <code class="option">--outside</code>
  83           options.
  84           The <em class="replaceable"><code>x</code></em> and
  85           <em class="replaceable"><code>y</code></em> values are specified as decimal
  86           degrees, negative for west or south.</p></dd><dt><span class="term"><code class="option">-r</code>, <code class="option">--require
  87         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Specify requirements for trackpoints to be written.
  88           <em class="replaceable"><code>x</code></em> is a string with the following
  89           flags:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">e</code></span></dt><dd><p>Print only waypoints which have an
  90                 elevation.</p></dd><dt><span class="term"><code class="option">p</code></span></dt><dd><p>Print only waypoints which have a position.</p></dd><dt><span class="term"><code class="option">t</code></span></dt><dd><p>Print only waypoints which have a
  91                 timestamp.</p></dd></dl></div></dd><dt><span class="term"><code class="option">-R</code>, <code class="option">--round
  92         <em class="replaceable"><code>x</code></em>=<em class="replaceable"><code>y</code></em>[<span class="optional">,<em class="replaceable"><code>x2</code></em>=<em class="replaceable"><code>y2</code></em>[<span class="optional">...</span>]</span>]</code></span></dt><dd><p>Round trackpoint element <em class="replaceable"><code>x</code></em> to
  93           <em class="replaceable"><code>y</code></em> decimals.</p><p>Example:</p><div class="blockquote"><blockquote class="blockquote"><p><code class="option">--round lat=4,lon=5,ele=1</code></p></blockquote></div></dd><dt><span class="term"><code class="option">-s</code>, <code class="option">--short-date</code></span></dt><dd><p>Use short date format.</p></dd><dt><span class="term"><code class="option">-S</code>, <code class="option">--save-to-file
  94         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Save the unconverted data to a file with a filename
  95           starting with the timestamp of the first trackpoint.
  96           The parameter string <em class="replaceable"><code>x</code></em> is added at
  97           the end of the filename.
  98           For the time being this option will ignore all other
  99           options.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If several files are specified on the command line,
 100             all data will be saved into only one file.
 101             This behaviour may change in the future.</p></div></dd><dt><span class="term"><code class="option">-t</code>,
 102         <code class="option">--create-breaks</code></span></dt><dd><p>Create breaks in track between points with a difference
 103           more than the number of seconds specified by the
 104           <code class="envar">PAUSE_LIMIT</code> variable.</p></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>x</code></em></code>,
 105         <code class="option">--time-shift
 106         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Move timestamps <em class="replaceable"><code>x</code></em> seconds
 107           forwards or backwards in output.
 108           <em class="replaceable"><code>x</code></em> can be a positive or negative
 109           integer.</p></dd><dt><span class="term"><code class="option">-v</code>, <code class="option">--verbose</code></span></dt><dd><p>Verbose output, can be repeated.</p></dd><dt><span class="term"><code class="option">--version</code></span></dt><dd><p>Print program version information.</p></dd><dt><span class="term"><code class="option">-w</code>,
 110         <code class="option">--strip-whitespace</code></span></dt><dd><p>Strip all unnecessary whitespace.</p></dd><dt><span class="term"><code class="option">-y</code>,
 111         <code class="option">--double-y-scale</code></span></dt><dd><p>Double Y scale (latitude).</p></dd><dt><span class="term"><code class="option">--debug</code></span></dt><dd><p>Print debugging messages.</p></dd></dl></div></div><div class="refsect1" title="Bugs and things that need to be done"><a id="gpst.bugs"></a><h2>Bugs and things that need to be done</h2><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Pretty incomplete in some areas.
 112         Some of the source formats are undocumented and thus incomplete.
 113         Some functionality is not working properly, for example the
 114         Postscript output.</p></li><li class="listitem"><p>Remove hardcodings.</p></li><li class="listitem"><p>Translate database column names to English.</p></li><li class="listitem"><p>Add more tests to cover all command-line options.</p></li></ul></div></div><div class="refsect1" title="Author"><a id="gpst.author"></a><h2>Author</h2><p>Made by <span class="personname"><span class="firstname">Øyvind</span> <span class="othername">A.</span> <span class="surname">Holm</span></span>
 115     <code class="email">&lt;<a class="email" href="mailto:sunny@sunbase.org">sunny@sunbase.org</a>&gt;</code>.</p></div><div class="refsect1" title="Copyright"><a id="gpst.copyright"></a><h2>Copyright</h2><p>Copyleft © <span class="personname"><span class="firstname">Øyvind</span> <span class="othername">A.</span> <span class="surname">Holm</span></span>
 116     <code class="email">&lt;<a class="email" href="mailto:sunny@sunbase.org">sunny@sunbase.org</a>&gt;</code>.
 117     This is free software; see the file <code class="filename">COPYING</code> for
 118     legalese stuff.</p></div><div class="refsect1" title="License"><a id="gpst.license"></a><h2>License</h2><p>This program is free software: you can redistribute it and/or
 119     modify it under the terms of the <em class="citetitle">GNU General Public
 120     License</em> as published by the <span class="orgname">Free Software Foundation</span>, either version
 121     3 of the License, or (at your option) any later version.</p><p>This program is distributed in the hope that it will be
 122     useful, but <span class="emphasis"><em>WITHOUT ANY WARRANTY</em></span>; without even
 123     the implied warranty of <span class="emphasis"><em>MERCHANTABILITY</em></span> or
 124     <span class="emphasis"><em>FITNESS FOR A PARTICULAR PURPOSE</em></span>.
 125     See the GNU General Public License for more details.</p><p>You should have received a copy of the GNU General Public
 126     License along with this program.
 127     If not, see <a class="ulink" href="http://www.gnu.org/licenses/" target="_top">http://www.gnu.org/licenses/</a>.</p></div><div class="refsect1" title="See also"><a id="gpst.seealso"></a><h2>See also</h2><p><span class="citerefentry"><span class="refentrytitle">gpsbabel</span>(1)</span></p></div></div></body></html>