doc/gpst.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4//EN" "../../../Tools/dtd/docbook-4.4/docbookx.dtd">
   3 <refentry id="gpst" lang="en">
   4   <!-- File ID: 84662624-f924-11dd-9043-0001805bf4b1 -->
   5   <refentryinfo>
   6     <date><![CDATA[$Id$]]></date>
   7   </refentryinfo>
   8   <refmeta>
   9     <refentrytitle>gpst</refentrytitle>
  10     <manvolnum>1</manvolnum>
  11   </refmeta>
  12   <refnamediv>
  13     <refname>gpst</refname>
  14     <refpurpose>Converts between various GPS formats.</refpurpose>
  15   </refnamediv>
  16   <refsynopsisdiv>
  17
  18     <cmdsynopsis>
  19       <command>gpst</command>
  20       <arg choice="opt">
  21         <replaceable>options</replaceable>
  22       </arg>
  23       <arg choice="opt" rep="repeat">
  24         <replaceable>file</replaceable>
  25       </arg>
  26     </cmdsynopsis>
  27
  28     <cmdsynopsis>
  29       <command>gpst</command>
  30       <arg choice="req">-S</arg>
  31       <arg choice="opt">
  32         <replaceable>options</replaceable>
  33       </arg>
  34       <arg choice="opt" rep="repeat">
  35         <replaceable>file</replaceable>
  36       </arg>
  37     </cmdsynopsis>
  38
  39   </refsynopsisdiv>
  40   <refsect1 id="gpst.description">
  41     <title>Description</title>
  42
  43     <variablelist>
  44
  45       <varlistentry>
  46         <term><option>--chronology</option></term>
  47         <listitem>
  48           <para>Check for broken chronology, warn about entries with an
  49           old timestamp.</para>
  50         </listitem>
  51       </varlistentry>
  52
  53       <varlistentry>
  54         <term><option>-d</option>, <option>--skip-dups</option></term>
  55         <listitem>
  56           <para>If succeeding identical coordinates are found, print
  57           only the first one and ignore the rest.</para>
  58         </listitem>
  59       </varlistentry>
  60
  61       <varlistentry>
  62         <term><option>-e</option>, <option>--epoch</option></term>
  63         <listitem>
  64           <para>Use seconds since 1970-01-01 00:00:00 GMT as date
  65           format.</para>
  66         </listitem>
  67       </varlistentry>
  68
  69       <varlistentry>
  70         <term><option>--fix</option></term>
  71         <listitem>
  72           <para>Comment out entries which is obviously wrong.
  73           Use together with <option>--chronology</option> to fix those
  74           kind of errors.
  75           Does not work with GPX output yet.</para>
  76         </listitem>
  77       </varlistentry>
  78
  79       <varlistentry>
  80         <term><option>--from-date
  81         <replaceable>x</replaceable></option></term>
  82         <listitem>
  83           <para>Used by the <literal>pgwupd</literal> format.
  84           Specifies from which date waypoints should be updated.
  85           No checks for valid date format here, let
  86           <application>PostgreSQL</application> take care of that.
  87           All variants it understands can be used here.</para>
  88         </listitem>
  89       </varlistentry>
  90
  91       <varlistentry>
  92         <term><option>-h</option>, <option>--help</option></term>
  93         <listitem>
  94           <para>Send a brief help summary to stdout.</para>
  95         </listitem>
  96       </varlistentry>
  97
  98       <varlistentry>
  99         <term><option>--inside</option></term>
 100         <listitem>
 101           <para>Print only trackpoints inside a rectangle specified by
 102           <option>--pos1</option> and <option>--pos2</option>.</para>
 103         </listitem>
 104       </varlistentry>
 105
 106       <varlistentry>
 107         <term><option>-n</option>, <option>--undefined
 108         <replaceable>x</replaceable></option></term>
 109         <listitem>
 110           <para>Use <replaceable>x</replaceable> as undefined
 111           value.</para>
 112         </listitem>
 113       </varlistentry>
 114
 115       <varlistentry>
 116         <term><option>--near</option></term>
 117         <listitem>
 118           <para>Add names of the three closest waypoints to the
 119           trackpoint.
 120           Unfinished and experimental, needs <citerefentry>
 121           <refentrytitle>gpsbabel</refentrytitle>
 122           <manvolnum>1</manvolnum> </citerefentry>, which is called from
 123           the program as
 124           <command>/usr/local/bin/gpsbabel</command>.</para>
 125         </listitem>
 126       </varlistentry>
 127
 128       <varlistentry>
 129         <term><option>-o</option>, <option>--output-format
 130         <replaceable>x</replaceable></option></term>
 131         <listitem>
 132           <para>Use output format <replaceable>x</replaceable>:</para>
 133           <variablelist>
 134
 135             <varlistentry>
 136               <term><option>clean</option></term>
 137               <listitem>
 138                 <para>TAB-separated format with longitude, latitude and
 139                 altitude.</para>
 140               </listitem>
 141             </varlistentry>
 142
 143             <varlistentry>
 144               <term><option>csv</option></term>
 145               <listitem>
 146                 <para>TAB-separated format:
 147                 <variablelist>
 148
 149                   <varlistentry>
 150                     <term>date</term>
 151                     <listitem>
 152                       <para>Date of trackpoint.
 153                       Format:
 154                       <literal><replaceable>yyyy</replaceable>-<replaceable>mm</replaceable>-<replaceable>dd</replaceable>T<replaceable>hh</replaceable>:<replaceable>mm</replaceable>:<replaceable>ss</replaceable>Z</literal>
 155                       unless the <option>--epoch</option> option is
 156                       specified.
 157                       If so, it’s represented as number of seconds since
 158                       1970-01-01 00:00:00 UTC.</para>
 159                     </listitem>
 160                   </varlistentry>
 161
 162                   <varlistentry>
 163                     <term>longitude</term>
 164                     <listitem>
 165                       <para>Longitude, decimal degrees.</para>
 166                     </listitem>
 167                   </varlistentry>
 168
 169                   <varlistentry>
 170                     <term>latitude</term>
 171                     <listitem>
 172                       <para>Latitude, decimal degrees.</para>
 173                     </listitem>
 174                   </varlistentry>
 175
 176                   <varlistentry>
 177                     <term>altitude</term>
 178                     <listitem>
 179                       <para>Altitude in metres above sea level.
 180                       Optional.
 181                       If not present, the corresponding TAB is also
 182                       printed, to keep the number of columns
 183                       intact.</para>
 184                     </listitem>
 185                   </varlistentry>
 186
 187                 </variablelist></para>
 188               </listitem>
 189             </varlistentry>
 190
 191             <varlistentry>
 192               <term><option>gpsml</option> (Default)</term>
 193               <listitem>
 194                 <para>Line-based XML which makes it easy to edit and
 195                 grep.
 196                 In the past, there was this big plan about making this
 197                 the default storage format, so it was declared as The
 198                 Honourable Default Output Format.
 199                 But using GPX is the way to go, so this will probably
 200                 change in the future.
 201                 It’s way too <foreignphrase>de facto</foreignphrase> and
 202                 widely used, so storing GPS data in anything else is
 203                 sheer waste of work.
 204                 Probably not finished yet.</para>
 205               </listitem>
 206             </varlistentry>
 207
 208             <varlistentry>
 209               <term><option>gpstrans</option></term>
 210               <listitem>
 211                 <para>The format generated by <citerefentry>
 212                 <refentrytitle>gpstrans</refentrytitle>
 213                 <manvolnum>1</manvolnum> </citerefentry>.</para>
 214               </listitem>
 215             </varlistentry>
 216
 217             <varlistentry>
 218               <term><option>gpx</option></term>
 219               <listitem>
 220                 <para>Not complete yet, but good enough in most
 221                 cases.</para>
 222               </listitem>
 223             </varlistentry>
 224
 225             <varlistentry>
 226               <term><option>pgtab</option></term>
 227               <listitem>
 228                 <para>TAB-separated format for import into
 229                 <application>PostgreSQL</application>.
 230                 Undefined values are written as <literal>\N</literal> if
 231                 the <option>--undefined</option> option is not
 232                 specified.</para>
 233                 <variablelist>
 234
 235                   <varlistentry>
 236                     <term><database class="field">date</database></term>
 237                     <listitem>
 238                       <para>Format:
 239                       <literal><replaceable>yyyy</replaceable>-<replaceable>mm</replaceable>-<replaceable>dd</replaceable>T<replaceable>hh</replaceable>:<replaceable>mm</replaceable>:<replaceable>ss</replaceable>Z</literal></para>
 240                     </listitem>
 241                   </varlistentry>
 242
 243                   <varlistentry>
 244                     <term><database class="field">coor</database></term>
 245                     <listitem>
 246                       <para>Format:
 247                       <literal>(<replaceable>lat</replaceable>,<replaceable>lon</replaceable>)</literal></para>
 248                     </listitem>
 249                   </varlistentry>
 250
 251                   <varlistentry>
 252                     <term><database class="field">ele</database></term>
 253                     <listitem>
 254                       <para>Altitude in metres above sea level.</para>
 255                     </listitem>
 256                   </varlistentry>
 257
 258                   <varlistentry>
 259                     <term><database class="field">name</database></term>
 260                     <listitem>
 261                       <para>Short name of closest waypoint.
 262                       Calculated in
 263                       <application>PostgreSQL</application>, so this
 264                       value is always <literal>\N</literal>.</para>
 265                     </listitem>
 266                   </varlistentry>
 267
 268                   <varlistentry>
 269                     <term><database class="field">dist</database></term>
 270                     <listitem>
 271                       <para>Distance in decimal degrees to closest
 272                       waypoint.
 273                       Calculated in
 274                       <application>PostgreSQL</application>, so this
 275                       value is always <literal>\N</literal>.</para>
 276                     </listitem>
 277                   </varlistentry>
 278
 279                   <varlistentry>
 280                     <term><database
 281                     class="field">description</database></term>
 282                     <listitem>
 283                       <para>Description of waypoint.
 284                       Calculated in
 285                       <application>PostgreSQL</application>, so this
 286                       value is always <literal>\N</literal>.</para>
 287                     </listitem>
 288                   </varlistentry>
 289
 290                 </variablelist>
 291               </listitem>
 292             </varlistentry>
 293
 294             <varlistentry>
 295               <term><option>pgwtab</option></term>
 296               <listitem>
 297                 <para>Output waypoints on a TAB-separated format:</para>
 298                 <variablelist>
 299
 300                   <varlistentry>
 301                     <term><database class="field">coor</database></term>
 302                     <listitem>
 303                       <para>Format:
 304                       <literal>(<replaceable>lat</replaceable>,<replaceable>lon</replaceable>)</literal></para>
 305                     </listitem>
 306                   </varlistentry>
 307
 308                   <varlistentry>
 309                     <term><database class="field">name</database></term>
 310                     <listitem>
 311                       <para>Title of waypoint.</para>
 312                     </listitem>
 313                   </varlistentry>
 314
 315                   <varlistentry>
 316                     <term><database class="field">ele</database></term>
 317                     <listitem>
 318                       <para>Elevation in metres above sea level.</para>
 319                     </listitem>
 320                   </varlistentry>
 321
 322                   <varlistentry>
 323                     <term><database class="field">type</database></term>
 324                     <listitem>
 325                       <para>Type of waypoint, same as the GPX <sgmltag
 326                       class="starttag">type</sgmltag> element.</para>
 327                     </listitem>
 328                   </varlistentry>
 329
 330                   <varlistentry>
 331                     <term><database class="field">time</database></term>
 332                     <listitem>
 333                       <para>Timestamp of waypoint.</para>
 334                     </listitem>
 335                   </varlistentry>
 336
 337                   <varlistentry>
 338                     <term><database class="field">cmt</database></term>
 339                     <listitem>
 340                       <para>Short waypoint description, used by the GPS
 341                       as a comment.
 342                       Same as the GPX <sgmltag
 343                       class="starttag">cmt</sgmltag> element.</para>
 344                     </listitem>
 345                   </varlistentry>
 346
 347                   <varlistentry>
 348                     <term><database
 349                     class="field">descr</database></term>
 350                     <listitem>
 351                       <para>Long description, not used by the GPS.
 352                       Same as the GPX <sgmltag
 353                       class="starttag">desc</sgmltag> element.</para>
 354                     </listitem>
 355                   </varlistentry>
 356
 357                   <varlistentry>
 358                     <term><database class="field">src</database></term>
 359                     <listitem>
 360                       <para>Source of data, same as the <sgmltag
 361                       class="starttag">src</sgmltag> GPX element.</para>
 362                     </listitem>
 363                   </varlistentry>
 364
 365                   <varlistentry>
 366                     <term><database class="field">sym</database></term>
 367                     <listitem>
 368                       <para>GPS symbol name.
 369                       Same as the <sgmltag
 370                       class="starttag">sym</sgmltag> GPX element.</para>
 371                     </listitem>
 372                   </varlistentry>
 373
 374                 </variablelist>
 375               </listitem>
 376             </varlistentry>
 377
 378             <varlistentry>
 379               <term><option>pgwupd</option></term>
 380               <listitem>
 381                 <para>Output waypoints as SQL transactions which updates
 382                 the <database class="field">name</database> and
 383                 <database class="field">dist</database> columns.</para>
 384               </listitem>
 385             </varlistentry>
 386
 387             <varlistentry>
 388               <term><option>poscount</option></term>
 389               <listitem>
 390                 <para>Creates a 3D plot where areas with many
 391                 trackpoints are higher than areas with less track
 392                 points.</para>
 393               </listitem>
 394             </varlistentry>
 395
 396             <varlistentry>
 397               <term><option>ps</option></term>
 398               <listitem>
 399                 <para>Postscript. Unfinished.</para>
 400               </listitem>
 401             </varlistentry>
 402
 403             <varlistentry>
 404               <term><option>svg</option></term>
 405               <listitem>
 406                 <para>Unfinished.</para>
 407               </listitem>
 408             </varlistentry>
 409
 410             <varlistentry>
 411               <term><option>xgraph</option></term>
 412               <listitem>
 413                 <para>Input format for <citerefentry>
 414                 <refentrytitle>xgraph</refentrytitle>
 415                 <manvolnum>1</manvolnum> </citerefentry>.</para>
 416               </listitem>
 417             </varlistentry>
 418
 419             <varlistentry>
 420               <term><option>ygraph</option></term>
 421               <listitem>
 422                 <para>Input format for <citerefentry>
 423                 <refentrytitle>ygraph</refentrytitle>
 424                 <manvolnum>1</manvolnum> </citerefentry>.</para>
 425               </listitem>
 426             </varlistentry>
 427
 428           </variablelist>
 429         </listitem>
 430       </varlistentry>
 431
 432       <varlistentry>
 433         <term><option>--outside</option></term>
 434         <listitem>
 435           <para>Print only trackpoints outside a rectangle specified by
 436           <option>--pos1</option> and <option>--pos2</option>.</para>
 437         </listitem>
 438       </varlistentry>
 439
 440       <varlistentry>
 441         <term><option>--pos1
 442         <replaceable>x1</replaceable>,<replaceable>y1</replaceable></option></term>
 443         <term><option>--pos2
 444         <replaceable>x2</replaceable>,<replaceable>y2</replaceable></option></term>
 445         <listitem>
 446           <para>Specifies corners of an area rectangle used by the
 447           <option>--inside</option> and <option>--outside</option>
 448           options.
 449           The <replaceable>x</replaceable> and
 450           <replaceable>y</replaceable> values are specified as decimal
 451           degrees, negative for west or south.</para>
 452         </listitem>
 453       </varlistentry>
 454
 455       <varlistentry>
 456         <term><option>-r</option>, <option>--require
 457         <replaceable>x</replaceable></option></term>
 458         <listitem>
 459           <para>Specify requirements for trackpoints to be written.
 460           <replaceable>x</replaceable> is a string with the following
 461           flags:</para>
 462           <variablelist>
 463
 464             <varlistentry>
 465               <term><option>e</option></term>
 466               <listitem>
 467                 <para>Print only waypoints which have an
 468                 elevation.</para>
 469               </listitem>
 470             </varlistentry>
 471
 472             <varlistentry>
 473               <term><option>p</option></term>
 474               <listitem>
 475                 <para>Print only waypoints which have a position.</para>
 476               </listitem>
 477             </varlistentry>
 478
 479             <varlistentry>
 480               <term><option>t</option></term>
 481               <listitem>
 482                 <para>Print only waypoints which have a
 483                 timestamp.</para>
 484               </listitem>
 485             </varlistentry>
 486
 487           </variablelist>
 488         </listitem>
 489       </varlistentry>
 490
 491       <varlistentry>
 492         <term><option>-R</option>, <option>--round
 493         <replaceable>x</replaceable>=<replaceable>y</replaceable><optional>,<replaceable>x2</replaceable>=<replaceable>y2</replaceable><optional>...</optional></optional></option></term>
 494         <listitem>
 495           <para>Round trackpoint element <replaceable>x</replaceable> to
 496           <replaceable>y</replaceable> decimals.</para>
 497           <para>Example:</para>
 498           <blockquote>
 499             <para><option>--round lat=4,lon=5,ele=1</option></para>
 500           </blockquote>
 501         </listitem>
 502       </varlistentry>
 503
 504       <varlistentry>
 505         <term><option>-s</option>, <option>--short-date</option></term>
 506         <listitem>
 507           <para>Use short date format.</para>
 508         </listitem>
 509       </varlistentry>
 510
 511       <varlistentry>
 512         <term><option>-S</option>, <option>--save-to-file
 513         <replaceable>x</replaceable></option></term>
 514         <listitem>
 515           <para>Save the unconverted data to a file with a filename
 516           starting with the timestamp of the first trackpoint.
 517           The parameter string <replaceable>x</replaceable> is added at
 518           the end of the filename.
 519           For the time being this option will ignore all other
 520           options.</para>
 521           <note>
 522             <para>If several files are specified on the command line,
 523             all data will be saved into only one file.
 524             This behaviour may change in the future.</para>
 525           </note>
 526         </listitem>
 527       </varlistentry>
 528
 529       <varlistentry>
 530         <term><option>-t</option>,
 531         <option>--create-breaks</option></term>
 532         <listitem>
 533           <para>Create breaks in track between points with a difference
 534           more than the number of seconds specified by the
 535           <envar>PAUSE_LIMIT</envar> variable.</para>
 536         </listitem>
 537       </varlistentry>
 538
 539       <varlistentry>
 540         <term><option>-T <replaceable>x</replaceable></option>,
 541         <option>--time-shift
 542         <replaceable>x</replaceable></option></term>
 543         <listitem>
 544           <para>Move timestamps <replaceable>x</replaceable> seconds
 545           forwards or backwards in output.
 546           <replaceable>x</replaceable> can be a positive or negative
 547           integer.</para>
 548         </listitem>
 549       </varlistentry>
 550
 551       <varlistentry>
 552         <term><option>-v</option>, <option>--verbose</option></term>
 553         <listitem>
 554           <para>Verbose output, can be repeated.</para>
 555         </listitem>
 556       </varlistentry>
 557
 558       <varlistentry>
 559         <term><option>--version</option></term>
 560         <listitem>
 561           <para>Print program version information.</para>
 562         </listitem>
 563       </varlistentry>
 564
 565       <varlistentry>
 566         <term><option>-w</option>,
 567         <option>--strip-whitespace</option></term>
 568         <listitem>
 569           <para>Strip all unnecessary whitespace.</para>
 570         </listitem>
 571       </varlistentry>
 572
 573       <varlistentry>
 574         <term><option>-y</option>,
 575         <option>--double-y-scale</option></term>
 576         <listitem>
 577           <para>Double Y scale (latitude).</para>
 578         </listitem>
 579       </varlistentry>
 580
 581       <varlistentry>
 582         <term><option>--debug</option></term>
 583         <listitem>
 584           <para>Print debugging messages.</para>
 585         </listitem>
 586       </varlistentry>
 587
 588     </variablelist>
 589
 590   </refsect1>
 591   <refsect1 id="gpst.bugs">
 592     <title>Bugs and things that need to be done</title>
 593
 594     <itemizedlist>
 595
 596       <listitem>
 597         <para>Pretty incomplete in some areas.
 598         Some of the source formats are undocumented and thus incomplete.
 599         Some functionality is not working properly, for example the
 600         Postscript output.</para>
 601       </listitem>
 602
 603       <listitem>
 604         <para>Remove hardcodings.</para>
 605       </listitem>
 606
 607       <listitem>
 608         <para>Translate database column names to English.</para>
 609       </listitem>
 610
 611       <listitem>
 612         <para>Add more tests to cover all command-line options.</para>
 613       </listitem>
 614
 615     </itemizedlist>
 616
 617   </refsect1>
 618   <refsect1 id="gpst.author">
 619     <title>Author</title>
 620
 621     <para>Made by <personname><firstname>Øyvind</firstname>
 622     <othername>A.</othername> <surname>Holm</surname></personname>
 623     <email>sunny@sunbase.org</email>.</para>
 624
 625   </refsect1>
 626   <refsect1 id="gpst.copyright">
 627     <title>Copyright</title>
 628
 629     <para>Copyleft © <personname><firstname>Øyvind</firstname>
 630     <othername>A.</othername> <surname>Holm</surname></personname>
 631     <email>sunny@sunbase.org</email>.
 632     This is free software; see the file <filename>COPYING</filename> for
 633     legalese stuff.</para>
 634
 635   </refsect1>
 636   <refsect1 id="gpst.license">
 637     <title>License</title>
 638
 639     <para>This program is free software; you can redistribute it and/or
 640     modify it under the terms of the <citetitle>GNU General Public
 641     License</citetitle> as published by the <orgname
 642     class="nonprofit">Free Software Foundation</orgname>; either version
 643     2 of the License, or (at your option) any later version.</para>
 644
 645     <para>This program is distributed in the hope that it will be
 646     useful, but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even
 647     the implied warranty of <emphasis>MERCHANTABILITY</emphasis> or
 648     <emphasis>FITNESS FOR A PARTICULAR PURPOSE</emphasis>.
 649     See the GNU General Public License for more details.</para>
 650
 651     <para>You should have received a copy of the GNU General Public
 652     License along with this program; if not, write to
 653 <address>The Free Software Foundation, Inc.
 654 <street>59 Temple Place</street>, <otheraddr>Suite 330</otheraddr>
 655 <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
 656 <country>USA</country></address></para>
 657
 658   </refsect1>
 659   <refsect1 id="gpst.seealso">
 660     <title>See also</title>
 661
 662     <para><citerefentry>
 663       <refentrytitle>gpsbabel</refentrytitle>
 664       <manvolnum>1</manvolnum>
 665     </citerefentry></para>
 666
 667   </refsect1>
 668   <!-- vim: set tw=72 ts=2 sts=2 sw=2 et fo=tcqw fenc=UTF-8 : -->
 669 </refentry>