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