branches/gpst.postgis/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.74.0" /></head><body><div class="refentry" lang="en" xml: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"><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" lang="en" xml:lang="en"><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">sted</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><dt><span class="term"><span class="database">avst</span></span></dt><dd><p>Distance to trackpoint in decimal degrees
  70                       from a defined “<span class="quote">home</span>” position.
  71                       This is calculated in
  72                       <span class="application">PostgreSQL</span>, so the
  73                       field value is always
  74                       <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:
  75                       <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
  76                       as a comment.
  77                       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.
  78                       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.
  79                       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
  80                 the <span class="database">sted</span> and
  81                 <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
  82                 trackpoints are higher than areas with less track
  83                 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
  84           <code class="option">--pos1</code> and <code class="option">--pos2</code>.</p></dd><dt><span class="term"><code class="option">--pos1
  85         <em class="replaceable"><code>x1</code></em>,<em class="replaceable"><code>y1</code></em></code>, </span><span class="term"><code class="option">--pos2
  86         <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
  87           <code class="option">--inside</code> and <code class="option">--outside</code>
  88           options.
  89           The <em class="replaceable"><code>x</code></em> and
  90           <em class="replaceable"><code>y</code></em> values are specified as decimal
  91           degrees, negative for west or south.</p></dd><dt><span class="term"><code class="option">-r</code>, <code class="option">--require
  92         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Specify requirements for trackpoints to be written.
  93           <em class="replaceable"><code>x</code></em> is a string with the following
  94           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
  95                 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
  96                 timestamp.</p></dd></dl></div></dd><dt><span class="term"><code class="option">-R</code>, <code class="option">--round
  97         <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
  98           <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
  99         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Save the unconverted data to a file with a filename
 100           starting with the timestamp of the first trackpoint.
 101           The parameter string <em class="replaceable"><code>x</code></em> is added at
 102           the end of the filename.
 103           For the time being this option will ignore all other
 104           options.</p><div class="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,
 105             all data will be saved into only one file.
 106             This behaviour may change in the future.</p></div></dd><dt><span class="term"><code class="option">-t</code>,
 107         <code class="option">--create-breaks</code></span></dt><dd><p>Create breaks in track between points with a difference
 108           more than the number of seconds specified by the
 109           <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>,
 110         <code class="option">--time-shift
 111         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Move timestamps <em class="replaceable"><code>x</code></em> seconds
 112           forwards or backwards in output.
 113           <em class="replaceable"><code>x</code></em> can be a positive or negative
 114           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>,
 115         <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>,
 116         <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" lang="en" xml:lang="en"><a id="gpst.bugs"></a><h2>Bugs and things that need to be done</h2><div class="itemizedlist"><ul type="disc"><li><p>Pretty incomplete in some areas.
 117         Some of the source formats are undocumented and thus incomplete.
 118         Some functionality is not working properly, for example the
 119         Postscript output.</p></li><li><p>Remove hardcodings, for example the “<span class="quote">home</span>”
 120         position used to calculate the <span class="database">avst</span> database column.</p></li><li><p>Translate database column names to English.</p></li><li><p>Add more tests to cover all command-line options.</p></li></ul></div></div><div class="refsect1" lang="en" xml:lang="en"><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>
 121     <code class="email">&lt;<a class="email" href="mailto:sunny@sunbase.org">sunny@sunbase.org</a>&gt;</code>.</p></div><div class="refsect1" lang="en" xml:lang="en"><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>
 122     <code class="email">&lt;<a class="email" href="mailto:sunny@sunbase.org">sunny@sunbase.org</a>&gt;</code>.
 123     This is free software; see the file <code class="filename">COPYING</code> for
 124     legalese stuff.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="gpst.license"></a><h2>License</h2><p>This program is free software; you can redistribute it and/or
 125     modify it under the terms of the <em class="citetitle">GNU General Public
 126     License</em> as published by the <span class="orgname">Free Software Foundation</span>; either version
 127     2 of the License, or (at your option) any later version.</p><p>This program is distributed in the hope that it will be
 128     useful, but <span class="emphasis"><em>WITHOUT ANY WARRANTY</em></span>; without even
 129     the implied warranty of <span class="emphasis"><em>MERCHANTABILITY</em></span> or
 130     <span class="emphasis"><em>FITNESS FOR A PARTICULAR PURPOSE</em></span>.
 131     See the GNU General Public License for more details.</p><p>You should have received a copy of the GNU General Public
 132     License along with this program; if not, write to
 133 </p><div class="address"><p>The Free Software Foundation, Inc.<br />
 134 <span class="street">59 Temple Place</span>, <span class="otheraddr">Suite 330</span><br />
 135 <span class="city">Boston</span>, <span class="state">MA</span> <span class="postcode">02111-1307</span><br />
 136 <span class="country">USA</span></p></div></div><div class="refsect1" lang="en" xml:lang="en"><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>