branches/gpst.gpsman-format/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.71.1" /></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 class="cmdsynopsis"><p><code class="command">gpst</code>  {-u} [
  12         <em class="replaceable"><code>options</code></em>
  13       ] [
  14         <em class="replaceable"><code>file</code></em>
  15       ...]</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
  16           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
  17           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
  18           format.</p></dd><dt><span class="term"><code class="option">--fix</code></span></dt><dd><p>Comment out entries which is obviously wrong.
  19           Use together with <code class="option">--chronology</code> to fix those
  20           kind of errors.
  21           Does not work with GPX output yet.</p></dd><dt><span class="term"><code class="option">--from-date
  22         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Used by the <code class="literal">pgwupd</code> format.
  23           Specifies from which date waypoints should be updated.
  24           No checks for valid date format here, let
  25           <span class="application">PostgreSQL</span> take care of that.
  26           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
  27           <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
  28         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Use <em class="replaceable"><code>x</code></em> as undefined
  29           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
  30           trackpoint.
  31           Unfinished and experimental, needs <span class="citerefentry"><span class="refentrytitle">gpsbabel</span>(1)</span>, which is called from
  32           the program as
  33           <span><strong class="command">/usr/local/bin/gpsbabel</strong></span>.</p></dd><dt><span class="term"><code class="option">-o</code>, <code class="option">--output-format
  34         <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
  35                 altitude.</p></dd><dt><span class="term"><code class="option">csv</code></span></dt><dd><p>TAB-separated format:
  36                 </p><div class="variablelist"><dl><dt><span class="term">date</span></dt><dd><p>Date of trackpoint.
  37                       Format:
  38                       <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>
  39                       unless the <code class="option">--epoch</code> option is
  40                       specified.
  41                       If so, it’s represented as number of seconds since
  42                       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.
  43                       Optional.
  44                       If not present, the corresponding TAB is also
  45                       printed, to keep the number of columns
  46                       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
  47                 grep.
  48                 In the past, there was this big plan about making this
  49                 the default storage format, so it was declared as The
  50                 Honourable Default Output Format.
  51                 But using GPX is the way to go, so this will probably
  52                 change in the future.
  53                 It’s way too <span class="foreignphrase"><em class="foreignphrase">de facto</em></span> and
  54                 widely used, so storing GPS data in anything else is
  55                 sheer waste of work.
  56                 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
  57                 cases.</p></dd><dt><span class="term"><code class="option">pgtab</code></span></dt><dd><p>TAB-separated format for import into
  58                 <span class="application">PostgreSQL</span>.
  59                 Undefined values are written as <code class="literal">\N</code> if
  60                 the <code class="option">--undefined</code> option is not
  61                 specified.</p><div class="variablelist"><dl><dt><span class="term"><span class="database">date</span></span></dt><dd><p>Format:
  62                       <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:
  63                       <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.
  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">dist</span></span></dt><dd><p>Distance in decimal degrees to closest
  67                       waypoint.
  68                       Calculated in
  69                       <span class="application">PostgreSQL</span>, so this
  70                       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.
  71                       Calculated in
  72                       <span class="application">PostgreSQL</span>, so this
  73                       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
  74                       from a defined “<span class="quote">home</span>” position.
  75                       This is calculated in
  76                       <span class="application">PostgreSQL</span>, so the
  77                       field value is always
  78                       <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:
  79                       <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
  80                       as a comment.
  81                       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.
  82                       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.
  83                       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
  84                 the <span class="database">sted</span> and
  85                 <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
  86                 trackpoints are higher than areas with less track
  87                 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
  88           <code class="option">--pos1</code> and <code class="option">--pos2</code>.</p></dd><dt><span class="term"><code class="option">--pos1
  89         <em class="replaceable"><code>x1</code></em>,<em class="replaceable"><code>y1</code></em></code>, </span><span class="term"><code class="option">--pos2
  90         <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
  91           <code class="option">--inside</code> and <code class="option">--outside</code>
  92           options.
  93           The <em class="replaceable"><code>x</code></em> and
  94           <em class="replaceable"><code>y</code></em> values are specified as decimal
  95           degrees, negative for west or south.</p></dd><dt><span class="term"><code class="option">-r</code>, <code class="option">--require
  96         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Specify requirements for trackpoints to be written.
  97           <em class="replaceable"><code>x</code></em> is a string with the following
  98           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
  99                 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
 100                 timestamp.</p></dd></dl></div></dd><dt><span class="term"><code class="option">-R</code>, <code class="option">--round
 101         <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
 102           <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
 103         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Save the unconverted data to a file with a filename
 104           starting with the timestamp of the first trackpoint.
 105           The parameter string <em class="replaceable"><code>x</code></em> is added at
 106           the end of the filename.
 107           For the time being this option will ignore all other
 108           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,
 109             all data will be saved into only one file.
 110             This behaviour may change in the future.</p></div></dd><dt><span class="term"><code class="option">-t</code>,
 111         <code class="option">--create-breaks</code></span></dt><dd><p>Create breaks in track between points with a difference
 112           more than the number of seconds specified by the
 113           <code class="envar">PAUSE_LIMIT</code> variable.</p></dd><dt><span class="term"><code class="option">-u</code>,
 114         <code class="option">--comment-out-dups</code></span></dt><dd><p>Comment out following data with identical position
 115           values, only print first entry.</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>,
 116         <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>,
 117         <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.
 118         Some of the source formats are undocumented and thus incomplete.
 119         Some functionality is not working properly, for example the
 120         Postscript output.</p></li><li><p>Remove hardcodings, for example the “<span class="quote">home</span>”
 121         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>
 122     <code class="email">&lt;<a 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>
 123     <code class="email">&lt;<a href="mailto:sunny@sunbase.org">sunny@sunbase.org</a>&gt;</code>.
 124     This is free software; see the file <code class="filename">COPYING</code> for
 125     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
 126     modify it under the terms of the <em class="citetitle">GNU General Public
 127     License</em> as published by the <span class="orgname">Free Software Foundation</span>; either version
 128     2 of the License, or (at your option) any later version.</p><p>This program is distributed in the hope that it will be
 129     useful, but <span class="emphasis"><em>WITHOUT ANY WARRANTY</em></span>; without even
 130     the implied warranty of <span class="emphasis"><em>MERCHANTABILITY</em></span> or
 131     <span class="emphasis"><em>FITNESS FOR A PARTICULAR PURPOSE</em></span>.
 132     See the GNU General Public License for more details.</p><p>You should have received a copy of the GNU General Public
 133     License along with this program; if not, write to
 134 </p><div class="address"><p>The Free Software Foundation, Inc.<br />
 135 <span class="street">59 Temple Place</span>, <span class="otheraddr">Suite 330</span><br />
 136 <span class="city">Boston</span>, <span class="state">MA</span> <span class="postcode">02111-1307</span><br />
 137 <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>