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