INTRODUCTION
COMMON USAGE
ADVANCED USAGE
ROUTE AND TRACK MODES
SYNTAX

THE FORMATS
DATA FILTERS

INDEX



INTRODUCTION

THE PROBLEM

There are simply too many gratuitously different file formats to hold waypoint, track, and route information in various programs used by computers.  GPX (http://www.topografix.com/gpx.asp) defines a standard in XML to contain all the data, but there are too many programs that don't understand it yet and too much data that are in an alternate formats.

THE SOLUTION

I needed to convert waypoints between a couple of formats, so I whipped up a converter and based it on an extensible foundation so that it was easy to add new formats.  Most file formats added so far have taken under 200 lines of reasonable ISO C so they can be stamped out pretty trivially.  Formats that are ASCII text delimited in some fixed way can be added with no programming at all via our 'style' mechanism.

GETTING IT / BUILDING IT

GPSBabel is distributed in source format that will work on about any operating system and as ready-to-run binaries for some operating systems, notably Windows.  See the "OS-Specific notes" at http://www.gpsbabel.org for instructions on those binary kits.

For operating systems where no binary is provided, you will have to build it.  The code should be compilable on any system with ISO C89 compilers.  It's been tested on UnixWare, OpenServer, OS/X, Linux, Solaris, and a variety of processors and compilers.

Libexpat is required for source builds.  If you get errors about expat.h being missing, you must either edit the Makefile to tell the compiler where it is or install it in a sensible place. Exapt can be downloaded from http://expat.sourceforge.net and is part of Apache so it's very portable.



COMMON USAGE

Invocation was meant to be flexible.   Unfortunately, that can sometimes lead to unwieldy command lines.

gpsbabel -?

will always show you the supported file types.   To use this program, just tell it what you're reading, where to read it from, what you're writing, and what to write it to.  For example:

gpsbabel -i geo -f /tmp/geocaching.loc -o gpx -F /tmp/geocaching.gpx

tells it to read the first file in geocaching.com format and create a new file in GPX format.

This command will read from a Magellan unit attached to the first serial port on a Linux system (device names will vary on other OSes) and write them as a geocaching loc file.  The second command does the same for windows.

gpsbabel -i magellan -f /dev/ttyS0 -o geo -F mag.loc
gpsbabel -i magellan -f com1 -o geo -F mag.loc

Optionally, you may specify "-s" in any command line.  This causes the program to ignore any "short" names that may be present in the source data format and synthesize one from the long name.  This is particularly useful if you're writing to a target format that isn't the lowest common denominator but the source data was written for the lowest common denominator.   I use this for writing data from geocaching.com to my Magellan so my waypoints have "real" names instead of the 'GC1234' ones that are optimized for NMEA-only receivers.   A geocacher with a Magellan receiver may thus find commands like this useful.

gpsbabel -s -i geo -f geocaching.loc -o magellan -F /dev/ttyS0
gpsbabel -s -i geo -f geocaching.loc -o magellan -F com1



ADVANCED USAGE

Argument are processed in the order they appear on the command line and are translated internally into a pipeline that data flows through when executed. Normally one would:

- read from one input
- optionally apply filters
- write into one output

but GPSBabel is flexible enough to allow more complicated operations such as reading from several files (potentially of different types), applying a filter, reading more data, then write the merged data to multiple destinations.

The input file type remains unchanged until a new -i argument is seen.  Files are read in the order they appear. So you could merge three input files into one output file with:

gpsbabel -i geo -f 1.loc -f 2.loc -f 3.loc -o geo -F big.loc

You can merge files of different types:

gpsbabel  -i geo -f 1.loc -i gpx -f 2.gpx -i pcx 3.pcx -o gpsutil -F big.gps

You can write the same data in different output formats:

gpsbabel -i geo -f 1.loc -o gpx -F 1.gpx -o pcx 1.wpt



ROUTE AND TRACK MODES

Most formats will make reasonable attempt to work transparently with waypoints, tracks, and routes.  Some formats, like 'garmin' and 'magellan' require the '-t' flag to work with tracks and '-r' to work with routes. '-w' is for waypoints, and is the default. So if you wanted to read all data from your unit into a gpx file, you might use a command like:

gpsbabel -t -r -w -i magellan -f com1:  -o gpx -F backup.gpx

Tracks and routes are advanced features and don't try to handle every possible hazard that can be encountered during a conversion.  If you're merging or converting files of similar limitations, things work very well.

Tracks and routes will sometimes be converted to a list of waypoints when necessary, f.i. when writing into one of the CSV formats. The inverse operation is not supported right now, so reading the converted track back from CSV will always result in a list of waypoints, not the original track.

The presence of "-s" on the command line tends to creats havoc on tracks and routes since many of these formats rely on internal linkages between such points and renaming them may break those linkages.  In general, don't use "-s" when tracks or routes are present.


SYNTAX
Usage:
    gpsbabel [options] -i INTYPE -f INFILE -o OUTTYPE -F OUTFILE
    gpsbabel [options] -i INTYPE -o OUTTYPE INFILE [OUTFILE]

The input type and filename are specified with the -i INTYPE and -f INFILE options.

The output type and filename are specified with the -o OUTTYPE and -F OUTFILE options.

If '-' is used for INFILE or OUTFILE, stdin or stdout will be used.

In the second form of the command, INFILE and OUTFILE are the first and second positional (non-option) arguments.

INTYPE and OUTTYPE must be one of the file types listed below, and may include options valid for that file type.  For example:

gpx
gpx,snlen=10
ozi,snlen=10,snwhite=1
are all valid file type specifications.
Command Line Options:
    -s               Synthesize shortnames
    -r               Process route information
    -t               Process track information
    -w               Process waypoint information [default]
    -N               No smart icons on output
    -x filtername    Invoke filter (place between inputs and output)
    -D level         Set debug level [0]
    -h, -?           Print detailed help and exit
    -V               Print GPSBabel version and exit



THE FORMATS



DATA FILTERS



INDEX
 

AN1 format
BAROIQ format
BCR format
CETUS format
COASTEXP format
Command Line
Common Usage
COPILOT format
CSV format
CUSTOM format
DISCARD filter
DISTANCE FROM A ROUTE (ARC) ARC filter
DNA format
DUPLICATE filter
EASYGPS format
File Formats
FUGAWI format
GARMIN format
GCDB format
GDB format
GEO format
GEOCACHING DB format
GLOGBOOK format
GOOGLE format
GPILOTS format
GPL format
GPSDRIVE format
GPSDRIVETRACK format
GPSMAN format
GPSPILOT format
GPSUTIL format
GPX format
HDOP (float) filter
HDOPANDVDOP filter
HIKETECH format
HOLUX format
HSANDV format
HTML format
IGC format
KML format
LOWRANCEUSR format
MAGELLAN format
MAGELLANX format
MAGGEO format
MAGNAV format
MAPCONVERTER format
MAPSEND format
MAPSOURCE format
MERGE filter
Modes
MOVE filter
MXF format
NAVICACHE format
NEMA format
NETSTUMBLER format
NIMA format
OPENOFFICE format
OZI format
PACK filter
PALMDOC format
PATHAWAY format
PCX5 format
PCX format
POLYGON filter
POP filter
POSITION filter
PSITREX format
PSITREX format
PSP format
PUSH filter
QUOVADIS format
RADIUS filter
REVERSE filter
Routes
S_AND_T format
SAPLUS format
SAROUTE format
SIMPLIFY filter
SORT filter
SPLIT filter
STACK filter
START / STOP filter
SWAP filter
Switches
Syntax
TABSEP format
TEF format
TEXT format
TIGER format
TITLE filter
TMPRO format
TOMTOM format
TPG format
TRACK filter
VCARD format
VDOP (float) filter
VITOSMT format
XCSV format
XMAP format
XMAPWPT format