
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.

THE FORMATS

    GPX

	This is the most capable and expressive of all the file formats
	supplied.    It is described at http://www.topografix.com/gpx.asp
	and is supported by EasyGPS, ExpertGPS, and man other programs
	described at http://www.topografix.com/gpx_resources.asp

    GEO

	geocaching.com spits up geocaching.loc files that are XML-ish but
	not quite GPX.   Becuase it's so close to GPX, this format is very
	well supported.

    MAGELLAN

	Waypoint serial upload and download works reliably to the 315, 330, 
	Meridian, and SportTrak family.  I expect it to work on any modern
	Magellan unit.

        As of 08/30/02, GPSBabel can also read and write the files that
        can be stuck on the SD memory cards with the Meridian models.
        Simply specify a file instead of a serial port.

        Communication errors are handled robustly and verification of
        data is enabled.

	Additional sub options:
	baud: may be 1200, 2400, 4800, 9600, 19200, but must match receiver.

    MAGELLANX

 	The SD card format used by the Magellan Explorist 400, 500, and 600.
	It's identical to the Magellan SD format used by Meridian, but allows
	longer waypoint names.
	
	You should name any file created with this format with a ".upt"
	extension so the firmware can read it.

    MAGGEO

        The SD card format used by the Magellan Explorist 400, 500, and
        600 to describe geocaches.  Notice what while the format can
        hold an infinite number of geocaches, the unit will read and
        silently discard all but 200 geocache POIs at a time.

        You should name any file created with this format with a ".gs"
        extension so the firmware can read it.

    GARMIN

        Waypoint serial upload and download works reliably under both
        POSIX and Windows.  I originally tested it with a Vista, a
        V, and a base eTrex, all graciously provided on loan by Joe
        Armstrong, but it's now regularly exercised on a 60CS (USB and
        serial) and many other models.  The communications library used,
        jeeps, claims to support most models of Garmin hardware.  Be
        sure the GPS is set for "Garmin mode" in setup and that nothing
        else (PDA hotsync programs, gpsd, getty, pppd, etc.) is using
        the serial port.

        GPSBabel supports the USB Garmins under Windows and on Linux and
        OS/X via libusb.  It's reported successful with VistaC, SummitC,
        60C, 60CS, 76C, 76CS, 96C, and Quest.  Some users report success
        with StreetPilot 2610 and some do not, but nobody's followed up
        with details on that.

        Currently, only a single USB unit at a time can be supported.  The
        device name to use on the command line is "usb:"   Thus, to read
	the waypoints from a Garmin USB unit and write them to a GPX file:

		gpsbabel -i garmin -f usb: -o gpx -F blah.gpx

        When reporting problems with Garmin, be sure to include the full
        unit model, firmware version, and be prepared to offer debugging
	dumps by adding "-D9" to the command line, like:

		gpsbabel -D9 -i garmin -f usb: -o gpx -F blah.gpx

        Custom icons are supported on units that support that.  Neither
        GPSBabel nor your firmware know what is associated with any
        given slot number.  They don't know that the picture you placed
        in the first slot is a happy face, they only know they're in the
        lowest numbered slot.  GPSBabel names the them consistently with
        Mapsource, so they are named 'Custom 0' through 'Custom 23'.

    GPSMAN

	GPS Manager can read and write formats that this converter doesn't
	understand.  The default formats (WGS84, DDD) work reliably.

    GPSUTIL

        GPSUtil has a simple file format of this program that
        runs on POSIX- compliant OSes like UNIX and Linux.
        Reads and writes of this format are reliable.  (I've
        also contributed to this program.)  It's available at
        http://www.cs.uakron.edu/~hennings/gpsutil/.

    TIGER

	The U.S. Census Bureau proives online mapping facilities.  This
	format is described at: http://tiger.census.gov/instruct.html.
	Do notice that this format is not the actual Tiger line mapping
	records, but rather the interface to their online mapping program.

    CSV

	There are a billion variants of Comma Separated Value data.  This
	is the one that makes Delorme S&A Deluxe 9 happy.   It's also a very
	simple program and useful for many other programs like spreadsheets.

        CSV is also the correct format for Lowrance MapCreate,
        their commercial mapping program, or GDM6 (their free
        waypoint manager) for iFinder which is available at
        http://www.lowrance.com/Software/GDM6/Default.asp

    LowranceUSR

	The Lowrance iFinder GPS series has the unique capability to
	output its data to an MMC card.  The data is saved to the card
	as a .USR file and can be read by your computer using a card
	reader.  Waypoints, routes, tracks are supported.  By default,
	Event marker icons are converted to waypoints.  Symbols tend
	to get lost in the translation.

	Additional options:
	ignoreicons	-	don't convert icons to waypoints
	merge		-	(USR output) merge all tracks into a single
					track with segments
	break		-	(USR input) break track segments into separate
					tracks

    XMap

	Delorme TopoUSA/XMap Conduit is one of the billion CSV variants 
	mentioned above.  It's just like S&A with the addition of a 
	completely pointless line at the beginning and end of the file.   
	This is the format used to hot-sync to XMap from withing TopoUSA.
	Done with help of Dan Edwards.

    XMapWpt

	Delorme XMapHandHeld Street Atlas USA is another of the billion 
	CSV variants.  This is the format used by XmapHH SA USA on
	(at least) PocketPC O/S.  Please see README.xmapwpt for more 
	information on it's intricacies.  This XMap is not to be confused
	with the XMap mentioned above. Contributed to GPSBabel by
	Alex Mottram.

    XCSV

	XCSV is an open-ended "Whatever Separated Values" parser / writer
	designed to work with user-supplied "style" files.  It should handle 
	at least a few thousand of the billion CSV variants available.  
	By itself, it doesn't comply to any format, however *most* CSV 
	variants can be described as a "style" and fine-tuned by the end 
	user.  For more information on it's use, please see README.style 
	in the style/ sub-directory of GPSBabel.  For an example of using 
	the XCSV module within your C program, look at the ozi.c, mxf.c, and
	xmapwpt.c sources in the GPSBabel directory.  This module was 
	contributed to GPSBabel by Alex Mottram.

	Additional Options:
	style	-	**REQUIRED** Path to XCSV style file.

	snlen	-	Maximum length of synthesized shortnames. 
	snwhite	-	Switch defining whether or not to allow whitespace
			in synthesized shortnames. 
			(0 = NO WHITESPACE, 1 = WHITESPACE OK).
	snupper	-	Switch defining whether or not to force uppercase 
			in shortnames. (0 = LEAVE AS IS, 1 = UPPERCASE ALL).
	
	NOTE:	sn* options require use of the '-s' command line option.

	Example Usage:
	gpsbabel -i xcsv,style=foo.style -f foo -o xcsv,style=bar.style -F bar
	gpsbabel -s -i gpx -f foo.gpx -o xcsv,style=my.style,snlen=8 -F bar

    MAPSEND

	Magellan was smart enough to document their file format to make
	creating software like this possible.

    MAPSOURCE

        Garmin Mapsource format appears compatible with the various
        members of that product family.  Icon mapping is attempted
        between different MapSource versions.  Altitude is supported,
        but proximity and depth are not.  Naming files *.mps will
        allow file->open in Mapsource to find the files more easily.
        Versions 3, 4 and 5 of the Mapsource data format are handled
        automatically on input and by default the output is version 5.
        (Until 3/2004, it was version 3, but since Mapsource updates
        are free, the convenience of having modern icon sets outweighs
        the backward compatibility concern.  Users of other versions
        can either upgrade or specify the switches to get get output in
        a compatible format.)  Waypoints, routes and tracklogs are all
        handled, but maps sets are ignored.

	Information on the Garmin Mapsource format was provided by Ian
	Cowley and Mark Bradley.  The code was implemented by Robert Lipe
	and Mark Bradley.

	Additional options:
	  snlen -		set the length of generated shortnames
	  mpsverout -	set the data format version of the output file
			(3,4 or 5)
	  mpsmergeout -	if the output file already exists, then the output
			is merged with it. This allows MapSource sections
			not being handled to remain intact (e.g. map sets)

    PsiTrex

        This is a text format created by KuDaTa's PsiTrex program for
        the Psion PDAs. The format can't be readily handled by XCSV, so
        this format is handled explicitly.  Waypoints, routes and tracks
        are all handled, with icon names used corresponding to verison
        1.13 of PsiTrex. This module was contributed to GPSBabel by Mark
        Bradley.

    PCX

        Garmin documents only PCX5, an older format limited to the
        lame NMEA six-character waypoint names that's treated as a
        second-class citizien in current versions of MapSource.  In
        Mapsource, use file->import to read these files.  If you name
	the files *.wpt, Mapsource will find them easier.

        In general, you should prefer the "mapsource" file format to
        this one.

    CETUS

	Cetus GPS (http://www.cetusgps.dk/) is a program for Palm/OS.  
	Working with Ron Parker and Kjeld Jensen, we can now read and write
	files for that program.   

    QUOVADIS

	QuoVadis for Palm OS (http://www.marcosoft.com/) is a program
	for Palm/OS. Working with record definitions provided by
	MarcoSoft and further experimentation by Bruce Thompson and
	"Fuzzy" from the Geocaching Forums to nail down the format
	precisely.

	Should work fine for import and export.

	One thing of note, QuoVadis stores all waypoints in a single
	Palm Database without using categories. This means that it may
	be difficult to keep personal waypoints separate from
	generated waypoints. What Bruce recommends is taking the
	QuoVadisMarkerDB.PDB file synced down from your Palm Powered
	device and extract the waypoints you personally set to a GPX
	file. Then using GPSBabel's joining capabilities generate a
	new PDB file from the personal file and the other waypoint
	files of interest.

	Currently the selection of icons to display and the scale at
	which to display them is hardcoded. Also there is no support
	for notes associated with waypoints. This will be addressed in
	a future revision.

    GPSPILOT

	The file format for GPSPILOT (http://www.gpspilot.com) was provided
	by Ron Parker.  The output from this module has been tested with 
        GPSPilot Tracker v5.05sx, but it is based on reverse-engineering
        so it may not work with all versions of all GPSPilot products.
	It had read-only support for Airport, Navaid, City and Landmark 
	files but will read and write Point files.

    MAGNAV

        Magellan NAV Companion for Palm/OS is not really designed for this 
        sort of use, but its file format is supported and with a little bit
        of patience you can both read and write NAV Companion waypoints.
        Please read README.magnav for further tips on getting waypoints
        in and out of NAV Companion.  This conversion is based on partially
        incomplete reverse-engineering of the record format, so it may not
        work with all versions of NAV Companion.  It has been tested with 
        version 2.10 and 3.20.
	
    PSP

	Microsoft's PocketStreets 2002 Pushpin (.PSP) format is not yet 
	completely documented.  THE .PSP MODULE DOES NOT WORK WITH MS 
	STREETS & TRIPS 2002 .EST FILES.  To create .PSP files from 
        Streets & Trips 2002, you will need to have PocketStreets support 
	installed.  Please note that MS Streets & Trips only *EXPORTS* 
	.PSP files. It does not import them.  MS Streets & Trips 2002 
	only imports CSV files.  To use .PSP files, simply copy them 
	over to the same folder on the mobile device as the map (.MPS), 
	and open PocketStreets.  It should also be noted that in the case 
	a pushpin is outside of the exported map area, the pin will be 
	"grayed-out" and unused in PocketStreets.  This is a good thing 
	as it allows us to create one big .PSP file that covers multiple 
	.MPS files.  Unfortunately, you need one .PSP file for every 
	.MPS file. :(

    MXF

        Maptech Exchange Format - Another CSV format file.  This format
        complies with (at least) Maptech Terrain Navigator, Terrain
        Professional, Take a Hike, and ExpertGPS import/export MFX.
        Contributed by Alex Mottram.

    DNA

	Navitrak DNA marker format - Another CSV format file.
	This is the format that is compatible with the DNA Desktop
	import/export command.  Reading the binary Markers.jwp 
	format directly off the data card is not supported yet.
	Contributed by Tim Zickus.

    OZI

        OziExplorer Waypoint Format - Another CSV format file.  Tested
        against OziExplorer v 3.90.3a / Shareware.  Contributed by Alex
        Mottram.

    TPG

	National Geographic Topo! Waypoint Format.  This filter 
	reads and writes .TPG files created by various editions of NG Topo! 
	This filter will *not* work with the newer combined .TPO files.  
	Contributed by Alex Mottram.

    HOLUX

        The Holuxgm-100 (e-fox) gps receiver uses standard compact
        flash cards.  File formats were provided by Holux-Taiwan
        http://www.holux.com.tw to the author.  The code was tested
        against version 2.27E1; other versions and receivers may
        work but have not been explictly tested.  Anyone with
        information on other Holux receivers is encouraged to contact
        jochen@bauerbahn.net.

        When copying the .wpo file to a flash card, the file must be
        named "tempwprt.wpo" as the receiver will ignore all other
        files.

        Comparing the waypoints of a .wpo files against other formats
        like .gpx you may notice a small difference in the latitude
        and longitude values.  The reason is the low resolution of
        the coordinates in the wpo file format.  In a .wpo file the
        reolution is 1/10"; in gpx for example it is 1/100".  A a practical
	matter, this loss is only about 1.7meters (5 feet).


        The generated waypoint failes can also be used by MapShow
        version 1.14.  This program is free of charge from the Holux web
        site.

        This format was contributed by Jochen Becker.

    TMPRO

        TopoMapPro Places File.  Reads and writes places files for use
        in TopoMapPro (http://www.topomappro.com).  As this file type
        can store links other than web links, anything that is not a
        http url will be discarded.  Note that this does not do datum
        conversions, so if your input file does not have WGS84/NZGD2000
        data, your output file won't either.
        Colour of waypoint icons defaults to red.

    GPSDRIVE
  
        GpsDrive way.txt file format. A space seperated format file. Tested
        against GpsDrive v 1.30 found @ http://www.kraftvoll.at/software.
        Contributed by Alan Curry.
	
    GPSDRIVETRACK
    
        Format used by GpsDrive to save tracks. Like GPSDRIVE a space
	seperated format file. See above for a link to GpsDrive.
	Contributed by Tobias Minich.

    Geocaching DB

	This is a PDA file format.    It was tested against version 2
	of GeocachingDB and a development snapshot of version 3.  
	Information on the file format came from Dougs Brat and Ron Parker.
	A particularly handy way to use GPSBabel on these files is to use
	GPSBabel to read a GPX file with Groundspeak  (geocaching.com) 
	extensions and let it write you a GeocachingDB file that contains
	the cache names, difficulty, terrain, and such.

	http://vip.hyperusa.com/~dougs/geocachingdb/geocachingdb.htm

    CoPilot

        This code is mostly intended to convert CoPilot Flight Planner
        for Palmd/OS atabases into other formats.  You probably should
        not use this to write CoPilot databases, although the code is
        there, because GPSBabel doesn't convert magnetic declination
        values.

        Questions, bug reports, etc, to ptomblin at xcski.com


	http://xcski.com/~ptomblin/CoPilot/
	http://navaid.com/CoPilot/

    EasyGPS

        This is the binary file format used by EasyGPS.  This format is
        seemingly being phased out in favor of GPX in newer versions of
        EasyGPS, but this allows conversions to and from the old binary
        .loc format.

	http://www.easygps.com/

        Information about and sketchy code to implement this file format
        were provided by Eric Cloninger.

    GpilotS

    	This is a Palm/OS file format ofr GPilotS.   It was tested against
	version 6.2.

	http://www.cru.fr/perso/cc/GPilotS/

	Neither tracks nor routes are supported at this time.

    s_and_t

        This is a format for importing into Microsoft Streets and Trips.
        It's been exercised on versions 2003, 2004, and 2005.  Detailed
        instructions on how to use it, including preserving hyperlinks,
        are at

	http://www.gpsbabel.org/formats/s_and_t/Importing_into_Microsoft_Streets_and_Trips_2003.html

    Gcdb

	This is the GeocachingDB by DougsBrat.  It works with v2 and v3
	of this program.

	http://vip.hyperusa.com/~dougs/geocachingdb/geocachingdb.htm

    NIMA

	This is a CSV format from the National Imagery and Mapping Agency.

    Fugawi

	This was a requested CSV format, *not* the proprietary binary format
        used by Fugawi. Like any other CSV format, GPSBabel cannot read tracks
        in this format, but converting a track into it and then importing as
        track in Fugawi works.

        It is known to work with Fugawi V3.1.4.635. When importing/exporting
        waypoints, one has to specify the order of fields as follows (names of
        fields may depend on the language used by Fugawi):
        - Name
        - Comment
        - Description
        - Latidude
        - Longitude
        - Altitude (metres)
        - Date (yyyymmdd/yymmdd)
        - Time of day (hhmmss)
        When importing tracks, use "[ignore]" instead of "Name", "Comment" and
        "Description".

	http://www.fugawi.com/

    custom

	This is a "kitchen sink" CSV format.   No known program will
	read it, but it's handy for simply converting an arbitrary file
	to text so it can be pulled into a spreadsheet or manipulated
	with text processing tools.

    tabsep

	Dumps all fields in a traditional Unix tab separated style.

    mapconverter

	Mapconverter is a format this is read by Mapopolis.com's mapconverter
	application.  Full details of it's usage are available in the file
	README.mapconverter.

    navicache

	This is the XML format that's used by Navicache.com for their
	geocaching data.  There are a number of fields in it that are 
	marked "required" but are Navicache-specific, so GPSBabel can not
	write these files, but we can still read them.

	http://www.navicache.com/cgi-bin/ib312a/ikonboard.cgi?act=ST;f=23;t=334

    coastexp

	This is the format used by CoastalExplorer (tm). The format is
	XML with items uniquely identified by Windows-style UUIDs.

	http://www.rosepointnav.com

    PsiTrex
	
	This is a text format created by KuDaTa's PsiTrex program for the Psion
	PDAs. The format can't be readily handled by XCSV, so this format is
	handled explicitly.  Waypoints, routes and tracks are all handled, with
	icon names used corresponding to verison 1.13 of PsiTrex.

    geoniche

        Geoniche is a Palm/OS application oriented for the off-road user.
	This module was contributed by Rick Richardson.

	http://www.nwlink.com/~raydar/GeoNiche/

    gpl

	This is the 'gpl' format as used in Delorme mapping products.
	It is a track format and contains little more than the tracklog
	of a GPS that was attached while driving.

	http://www.frontiernet.net/~werner/gps/

    saroute

	This is a catch-all used by many Delorme mapping products and
	reads the anr, rte, and rtd formats as either tracks or routes.

        The 'turns_only' option causes GPSBabel to read only the waypoints 
        associated with named turns.  This should create a list of waypoints 
        that correspond to the itinerary from Street Atlas.
	
        The 'turns_important' option only makes sense in conjunction with 
        the 'simplify' filter.  It ensures that the route simplification 
        process will remove the points corresponding to turns only after
        it has removed all other route points.

        Both options only apply to route files from newer versions of 
        DeLorme software; older versions didn't store the turn information
        with the route.

    saplus

        This format is for Street Atlas USA 2004 Plus.  

        For geocachers importing data from a tool like GSAK or Spinner,
        import the file twice in XData.  One will create a file with the
        Cache description as a hyperlink on the flag.  This can clutter
        up the screen and when you try to zoom in, it causes problems.
        So the second one will only have a flag.  Thus you can turn off
        and on which one you want to view.  The first time you import
        the file, in the assign field types, check the circle above Full
        Name and then next.  The second time you import the file do not
        check any circle and in the second to last column, change URL to
        none and then click next. Use the same name you used the first
        time but add -Flag to it.

    nmea

	This format is the file representation of the NMEA0183 log and
	waypoint format.   Representative programs include:

	http://www.genimap.fi/kuluttajatuotteet/alue2.asp?folder=38&subfolder=16662&2057

	http://homepages.tig.com.au/~robk/datalogger.html
	http://www.gpstm.com/eng/features_eng.htm
	http://www.gpsmaster.nl/
	http://www.silcom.com/~rwhately/index.html
	http://www.visualgps.net/VisualGPSce/default.htm
	http://www.gpsu.co.uk/
	http://www.kolumbus.fi/eino.uikkanen/geoconvgb/index.htm
	http://www.commlinx.com.au/GPS_recorder.htm

    TEXT

        This is a simple human readable version of the data file, handy for
        listings of any type of waypoint files.  Use the 'nosep' option
        to suppress the lines of dashes between entries.  Use the 
        'encrypt' option to encrypt hints from Groundspeak GPX files.
        Use the 'logs' option to include Groundspeak cache logs.

        The following command line reads a GPX file with Groundspeak extensions
        and writes a text file with encrypted hints:

        gpsbabel -i gpx -f 12345.gpx -o text,encrypt -F 12345.txt

    HTML

        HTML output generates a single HTML file of all of the waypoints in
        the input file.  It supports a number of Geocaching GPX extensions,
        as well as filters out potentially harmful HTML from the input file
        while maintaining almost all of the source HTML formatting.  Use the
        'stylesheet' option to specify a CSS stylesheet to be used with the 
        resulting HTML file.  Use the 'encrypt' option to encrypt hints from
        Groundspeak GPX files.  Use the 'logs' option to include Groundspeak 
        cache logs.

        The following command line reads a GPX file with Groundspeak extensions
        and writes an HTML file with encrypted hints that is rendered using a
        custom stylesheet:

        gpsbabel -i gpx -f 12345.gpx \
                 -o html,stylesheet=green.css,encrypt -F 12345.html

    PALMDOC
 
        PalmDoc output is similar to Text output, except that it generates 
        a Palm Database (PDB) file suitable for use with programs like 
        CSpotRun, TealDoc, AportisDoc, Palm Reader, and others.  The resulting
        file also contains bookmarks to make it easy to jump to a particular
        waypoint.  To suppress the dashed lines between waypoints, use the 
        'nosep' option.  To specify a name for the document, use the 'dbname'
        option.  Use the 'encrypt' option to encrypt hints from Groundspeak
        GPX files.  Use the 'logs' option to include Groundspeak cache logs.
	If you would like the generated bookmarks to start with the short name
        for the waypoint, specify the 'bookmarks_short' option.  This is
        particularly useful when used in combination with the 'sort' filter.

        The following command line reads a GPX file with Groundspeak extensions
        and writes a Palm document with encrypted hints and logs:

        gpsbabel -i gpx -f 12345.gpx \
                 -o "palmdoc,dbname=Unfound Geocaches,encrypt,logs" \
                 -F 12345.pdb

    Netstumbler

        NetStumbler 0.4 Summary File -- Another CSV format file.  The
        default behavior when creating waypoints is to use the SSID for
        the short name, and information about the access point for the
        description.  When the SSID is not unique, is not available, or
        consists of whitespace, a shortname is synthesized.  The snmac
        option uses the MAC address for the shortname, and includes
        the unmodified SSID in the description.  Different icons are
        assigned to encrypted, non-encrypted, stealth, and non-stealth
        access points; these may be changed with options.  Import only.

	Additional options:

	  nseicon  - Name of icon used for non-stealth encrypted access points

	  nsneicon - Name of icon used for non-stealth non-encrypted access
		     points

	  seicon   - Name of icon used for stealth encrypted access points

	  sneicon  - Name of icon used for stealth non-encrypted access points

	  snmac    - Always use the MAC address as the shortname.

    IGC

        FAI/IGC Data File -- Used by the international gliding community to
        record gliding flights.  IGC files can be converted to and from tracks
        representing recorded flights, and routes representing task
        declarations in other formats.

    BAROIQ

        Serial download protocol for the Brauniger IQ series of barograph
        recording flight instruments.  Creates a track of altitude vs time
        which can be merged with a GPS track of the same flight to create a
        three dimensional IGC file.

    hsandv

        HSA Systems Endeavour Navigator format - will import both the old
        version 4.x binary files, and the newer XML based ones. 
        Only writes the new XML (5.0 and above) format. (use the .exp 
	extension)

    vCARD

        The vCard output is intended to be in a format that enables
        waypoints to be viewed with an Apple iPod. This is achieved by
        mapping waypoint fields into vCard fields that can be displayed
        as 'Contacts' on the iPod. With the iPod mounted as a hard disk
        (see your iPod manual for instructions), the resulting VCF
        file should be moved into the iPod 'Contacts' folder. As an
        alternative, Mac OS X users may prefer to drag the VCF file into
        their address book and synchronize with the iPod using iSync. By
	default hints are unencrypted; use the 'encrypt' option to
        encrypt the hints.

    Hiketech

        This is the .gps format used by the Mac OS X applications
        written by HikeTech. These include TopoDraw, Link2GPS, and
        GPSWrite. More information about these products can be found at
        http://www.hiketech.com

    glogbook

        This is the XML format used by the Garmin Logbook product that
        ships with Forerunner and Foretrex.

	http://www.garmin.com

    KML

	We have sketchy support for KML, the Keyhole Markup Language.
	There are many features in this file format that we don't yet
	support, but simple waypoint lists convert fine.

    GOOGLE
        
        This format is designed to read the XML emitted when you tack
        "&output=js" onto the end of a Google Maps route URL (use the 
        "link to this page" option to get a usable URL.)  This allows 
        you to plan a route using Google Maps, then download it and use 
        it in your own mapping program or GPS receiver.  If you use a 
        Unix-compatible operating system, this shell script might be 
        useful:

        #!/bin/sh
	FROM="233 S. Upper Wacker Dr, Chicago, IL"
	TO="1060 W. Addison St, Chicago, IL"
        wget -O - "http://maps.google.com/maps?q=$FROM to $TO&output=js" \
           2>/dev/null >google_map.js

        gpsbabel -i google -f google_map.js -o gpx -F google_map.gpx

        Note that Internet Explorer has been observed to damage the
        XHTML beyond recognition so use a better browser to save the
        pages such as Firefox or Mozilla.

    TEF

        TEF, internal called "TourExchangeFormat", is a XML based 
	export format, used by Map&Guide "Motorrad-Routenplaner 2005/06".
	Another posibility to exchange data with this are the .bcr files,
	which are sopprted by GPSbabel in both directions (see BCR).
	Via XML this software can only export routing data.  
	So we don't support writing. 
	
	With the option "routevia" you can eliminate calculated route
	points from tef source file.
	
	gpsbabel -r -i tef,routevia -f in.xml -o gpx -F out.gpx

    PathAway

        PathAway is a Palm software designed for handling "most" GPS
        devices (including BlueTooth). In this time (i mean 2005) a free
        tool to convert this database is located on the homepage of
        PathAway (www.pathaway.com). But i've read there ... for windows
        and the output formats are also very limited.

    AN1

        This format supports the DeLorme ".an1" drawing file format.  It
        can currently be used to either read or write drawing files.  If
        you use this format to create drawing files with routes or waypoints
        from another source, it will currently create "Red Flag" symbols 
        for waypoints, and thick red lines for routes or tracks.  It is
        possible to merge two drawing layers by doing something like this:

        gpsbabel -i an1 -f one.an1 -f two.an1 -o an1 -F merged.an1

        In this case, the merged data will contain all of the properties
        of the original data.

        Currently, GPSBabel only writes drawing layers, as opposed to road, 
        track, and other specialized layers.  If your input file is a road, 
        track, trail, or waypoint layer, you should not attempt to write to 
        an .an1 file as the results may be unpredictable.  Note that this 
        also applies to merging files, so you can't currently merge two road
        layers with GPSBabel (officially; there is an unsupported "type" 
        option that works in limited cases.)

    TomTom

	This format can read and write TomTom .ov2 (POI) files, as used by the 
        TomTom GO and TomTom Navigator.  It has been tested with an original
        TomTom GO running version 5.00 of the TomTom software.  There may be
        some records that confuse the input module - if you have an example
        of such a record "in the wild", and you aren't restricted from sharing
        it, we encourage you to post to the gpsbabel-misc mailing list to 
        contact a developer.

        Note that in addition to the .ov2 file, you will need a .bmp file for
        the icon.  It should be 22x22 and 16 colors, and have the same name
        (not including the extension) as the .ov2 file.

    VitoSMT

	Vito Navigator II is a Pocket PC GPS application.  This format reads
	a Vito Navigator II .SMT track file and can work in either waypoint
	or track mode.  The speed, heading and Dilution of Position data
	is written in the notes field.

	Support for writing .SMT tracks is very experimental and may crash
	VitoNavigator II on the Pocket PC.

    GDB

        Support for the "Garmin GPS Database" format used by default in
        MapSource versions since release 6.0. By default we create gdb's
        of version 2.  Version 2 is used in Mapsource 6.3 and 6.5.

        Garmin GPS database is an undocumented file format. The
        basic info for this module comes from the existing MapSource
        conversion code.

        Additional options:

            ver - set the data format version of the output file
            (currently 1 or 2); 2 is our default.
	     via - Drop hidden route points (means calculated stuff) 
	    cat - default category on output (1..16)

    BCR
    
	This file format (extension .bcr) is used in
	"Motorrad Routenplaner 2002-..." by Map&Guide. It is a route-onle
	format. If you own a newer release (2005...) you can also use 
	the XML export and convert via 
	"gpsbabel ... -i tef ..." to your preferred format. 
	
	May be there are other products from Map&Guide using the format.
	
	Coordinates are stored in Mercator format. The calculation between
	this and our internal format can result in visible differences.
	Experience reports are welcome.
	
	Options:
	
	  index -  If more then one route are present in source data, with
	           this option you can determine, which of this should used
		   for the output. The range is 1 to number routes in input.
		   If you don't use this, only the first route will be
		   converted.
	  name -   Not every input format has a real name for routes in 
	           their data. So you can give the route a nice name.
	  radius - Overwrites the default value of 6371000.0 meters for
	           the earth radius. My be this can help to reduce 
		   differences.
		   
	An example with all options:
	
	gpsbabel -r \
		 -i gpx -f in.gpx
	         -o bcr,index=1,name="From A to B",radius=6371012 \
		 -F a_to_b.bcr
	
    OPENOFFICE
	Tab seperated export-all (except geocaching data) file format. 
	Intended to serve as source for number-processing applications
	like OpenOffice, Ploticus and others. Tab was chosen as delimiter
	because it is a) supported by both OpenOffice and Ploticus and
	b) is not ',', so you can use 'sed -i "s/./,/g" <x>.csv' to adapt it to
	locales where ',' is used as decimal seperator.
	Contributed by Tobias Minich.
	
DATA FILTERS

        GPSBabel supports data filtering.  Data filters are invoked from
        the command line via the '-x' option.  It should be noted that
        data filters are invoked in the internal pipeline at the point
        that corresponds to their position on the command. This implies
        that specifying a filter before reading any data ('-x <filter>
        -f <file>'), despite being legal, will not have any effect. The
        advantage is that filters can be used intermittently between
        several variations of input and output functions.  It should
        also be noted that filtering data from different input types can
        sometimes produce undesirable results due to differences in the
        native data formats.

        Beware that most filters only apply to a certain kind of
        data. This is usually indicated below by referring to points,
        tracks or routes in the first sentence which describes each
        filter or in the table at http://www.gpsbabel.org/capabilities.html .

    POSITION

	The position filter is designed to remove points based on their
	proximity to each other.  Distances can be passed on the command 
	line by passing the distance=XXX option to the filter.  Distance
	options may be expressed in feet (distance=3f) or meters 
	(distance=1m).  The default is zero feet, essentially a duplicate
	position.  

	For example:

	gpsbabel -i geo -f 1.loc -f 2.loc -x position,distance=1f \
	         -o mapsend -F 3.wpt

	would remove multiple points that are within 1 foot of each other,
	leaving just one.

	You can also specify the "all" option, which would remove all 
	of the points rather than leaving one.

    RADIUS

	The radius filter is designed to include points based on their
	proximity to a central point.  Distances and the central point 
	are declared on the command line by passing the distance=X.XX,
	lat=X.XX, and lon=X.XX options to the filter.  Distance options 
	may be expressed in miles (distance=3M) or kilometers (distance=3K).
	The default is zero miles.  Additionally, the exclude option may 
        be specified to reverse the effect of the filter, so that points 
        further from the center are kept and closer points are discarded.

	For example:

	gpsbabel -i geo -f 1.loc -x radius,distance=1.5M,lat=30.0,lon=-90.0 \
	         -o mapsend -F 2.wpt

	would include only points within 1.5 miles of N30.000 W90.000 


    DUPLICATE

	The duplicate filter is designed to remove duplicate points based
	on their shortname (traditionally a waypoint's name on the GPS
	receiver), and/or their location (to a precision of 6 decimals).
	This filter supports two options that specify how duplicates will
        be recognized, "shortname" and "location".  Generally, at least one 
        of these options is REQUIRED.  For example:

	gpsbabel -i gpx -f 1.gpx -f 2.gpx -x duplicate,location,shortname \
	         -o gpx -F merged_with_no_dupes.gpx

	would remove points that have duplicate shortnames *AND* duplicate
	locations.  The result would be a GPX file that more than likely
	contains only unique points and point data.

        The duplicate filter can also take an "all" option.  If you specify 
        that option, all instances of a duplicated waypoint will be removed,
        not just the second and subsequent instances.  If your input file
        contains waypoints A, B, B, and C, the output file will contain 
        waypoints A, B, and C without the "all" option, or just A and C 
        with the "all" option.  This option can be useful as an "ignore
        list" in some circumstances.

	Finally, the duplicate filter takes a "correct" option.  If you
	specify that option, the latitude and longitude frmo later duplicates
	will replace the latitude and longitude in earlier waypoints.  You
	can use this to apply a list of "waypoint corrections" to a larger
	file, while keeping all of the other details from the larger file.

    DISTANCE FROM A ROUTE (ARC)
    ARC

        The arc filter is designed to include points based on their
        proximity to an arc, which is a series of connected line
        segments similar to a route or a track but without any
        associated data other than the coordinates.

        The arc is defined in a file whose name must be provided with
        the file=XXXX option to the filter.  That file contains pairs
        of coordinates for the vertices of the arc, one coordinate pair
        per line.  Comments may be included by preceding them with a '#'
        character.  An arc file looks something like this sample:

	  # Lima Road/SR3 north of Fort Wayne, Indiana
	  41.150064468    -85.166207433
	  41.150064468    -85.165371895
	  41.149034500    -85.165157318
	  41.147832870    -85.164771080
	  41.146631241    -85.164384842
	  41.144270897    -85.163655281
	  41.141953468    -85.162882805

        An arc file may optionally contain gaps in the arc.  You can 
        specify such a gap by inserting a line containing "#break" 
        either on a line by itself or after the coordinates of the
        starting point of the new arc segment.

        In addition to the file containing the arc, you should also
        specify the maximum distance from the arc that will be accepted;
        that distance is declared on the command line with the
        distance=X.XX option to the filter.  Distance options may be
        expressed in miles (distance=3M) or kilometers (distance=3K).
        The default is zero miles.  You may also specify the exclude option,
        which causes GPSBabel to only include points that are further than
        the specified distance from the arc.

	For example, assuming the arc above is in a file called "lima_rd.txt":

	gpsbabel -i geo -f 1.loc -x arc,file=lima_rd.txt,distance=1 \
		-o mapsend -F 2.wpt

	would include only points within one mile of the section of Lima Road
	covered by the arc.

    POLYGON

        The polygon filter includes points if they are inside of a polygon.
        A polygon file looks like an arc file, except that the arc it 
        describes must be a closed cycle.  That is, for a simple polygon,
        the first and last points must be the same.  Here's a square:

          # A square (not really) polygon
          41.0000       -85.0000
          41.0000       -86.0000
          42.0000       -86.0000
          42.0000       -85.0000
          41.0000       -85.0000

        Polygons may include islands and holes.  To specify an island or a 
        hole, just append it to the main polygon.

        As with the arc filter, you specify a polygon by specifying the name
        of the polygon that contains it, using the file option.  You can also
        specify the exclude option, which reverses the operation of the filter
        so that it only includes points that are NOT in the polygon.

        Note that this filter currently will not work properly if your polygon 
        contains one or both poles or if it spans the line of 180 degrees 
        east or west longitude.  

        For example, assume you have a polygon file that defines the border of
        your county, called mycounty.txt.  This command line will give you only 
        the points in your county:

	gpsbabel -i geo -f 1.loc -x polygon,file=mycounty.txt \
	  	 -o mapsend -F 2.wpt

    SIMPLIFY

	The Simplify filter is used to simplify routes and tracks for use
        with formats that limit the number of points they can contain. 
        The filter takes one required parameter, which is the maximum 
        number of points a route may contain.  It attempts to remove 
        points from each route until the number of points is at or below 
        the given maximum, while also attempting to preserve the shape of
        the original route as much as possible.  

        The quality of the results will vary depending on the density of 
        points in the original route and the length of the original route.

        For example, suppose you have a route from Street Atlas 2003 that 
        you wish to use with a Magellan GPS receiver that only supports up
        to 50 points in a route:

        gpsbabel -r -i saroute -f RoadTrip.anr -x simplify,count=50 \
                 -o magellan -F grocery.rte

    REVERSE
	
	The reverse filter is used to reverse tracks and routes.   It's
	mostly useful for those few formats where track/route sequence matters
	and there isn't a way to reverse them using the program itself.

        The reversal is performed in the laziest way possible.
        Timestamps are kept with the original waypoints so the resulting
        track or route will have the interesting characteristic that
        time runs backwards.  This tends to make Magellan Mapsend,
        in particular, do a wierd thing and place each waypoint on a
        separate day.

        Additionally, if you're using this to reverse a route that
        navigates, say, an exit ramp or a one way street, you will be in
        for unpleasant ride. application cares about timestamps

    SORT

        This simple filter allows you to alphabetize waypoints by
        shortname or by description.  It has a special suboption (gcid)
        to sort by geocaching.com waypoint ID's when the input comes
        from a GPX file that has GC numbers in it.

    STACK
 
        This filter is designed to solve advanced problems that involve
        shuffling multiple lists of waypoints.  It has three distinct
        sets of suboptions:
 
        PUSH
 
            Pushes the current list of waypoints onto the stack.  If
            the 'copy' suboption is specified, a copy of the current
            list is pushed onto the stack; otherwise, the current
            list is cleared.
                  -x stack,push
                  -x stack,push,copy

        POP

            'Pops' the top list of waypoints off of the stack.  What is
            done with that list depends on the suboption specified.  If
            the 'append' suboption is specified, the top list of waypoints
            from the stack is added to the end of the current list of
            waypoints.  If the 'discard' option is specified, the top
            list of waypoints is removed from the stack and discarded,
            leaving the current list of waypoints unchanged.  If the
            'replace' option is specified, or if no option is specified,
            the top list of waypoints from the stack replaces the current
            list of waypoints; the previous contents of the current list
            are discarded.
                  -x stack,pop 
                  -x stack,pop,discard
                  -x stack,pop,append

        SWAP

            Swaps the current list of waypoints with a list from the 
            stack.  If no further options are specified, the current 
            list is swapped with the top list on the stack.  If the 
            'depth' option is specified, it indicates which item on 
            the stack should be swapped.  
                  -x stack,swap        
                  -x stack,swap,depth=2 

        The stack can be used in conjunction with other filters to 
        implement a "union" or "logical or" functionality.  The basic
        idea is to use the stack to store copies of the original list 
        of waypoints, then use the 'swap' function to replace each copy
        with a filtered list.  Finally, append all of the filtered lists
        to create one big list, which is then output.  The following
        example finds a list of all points that are either inside county A
        or inside county B.  Any points that are inside both counties are
        duplicated (but the duplicates can be removed with the DUPLICATE
        filter; see above.)

           gpsbabel -i gpx -f in.gpx \
                    -x stack,push,copy \
                    -x polygon,file=county_a.txt \    
                    -x stack,swap \
                    -x polygon,file=county_b.txt \
                    -x stack,pop,append \
                    -o gpx -F out.gpx

        This example reads a large list of waypoints and extracts the
        points within 20 miles of each of two cities, writing the 
        waypoint descriptions into two different PalmDoc files and 
        exporting all of the points to the GPS receiver:

           gpsbabel -i gpx -f indiana.gpx \
                    -x stack,push,copy \
                    -x radius,lat=41.0765,lon=-85.1365,distance=20m \
                    -o palmdoc,dbname=Fort\ Wayne -F fortwayne.pdb \
                    -x stack,swap \
                    -x radius,lat=39.7733,lon=-86.1433,distance=20m \
                    -o palmdoc,dbname=Indianapolis -F indianapolis.pdb \
                    -x stack,pop,append \
                    -o magellan -F fwaind.wpt
 

    TRACK

	( !!! This filter always drops empty tracks !!! )
	
        The track filter is a tool for manipulating track lists. 
	The following options are available:

        TITLE

            Gives the new track(s) a basic title. Basic means if more
            than one track is created by filter the title will be
            expanded with the date the new track. Special formats (see
            UNIX date or strftime for details) are possible.

            gpsbabel -t \
		-i gpx -f in.gpx  \
	          -x track,pack,split,title="ACTIVE LOG-%D" \ 
		-o gpx -F out.gpx PACK
		
	MOVE
	
	    Change the time of all trackpoints. This is useful if
	    your track has moved by one or more hours through a
	    time zone problem.   The following example will shift
	    your track to be one hour later.

	    gpsbabel -t \
		     -i gpx -f in.gpx \
		     -x track,move=+1h,pack,title="ACTIVE LOG" \
		     -o gpx -F out.gpx
		     
	START / STOP
	
	    Filter tracks against time borders. All points outside
	    this range will be dropped. The date-time paramters
	    have to be in form of YYYYMMDDHHMMSS; but you may specify
 	    only the most significant portion represented in the the 
	    leftmost fields.  See the example, where the time is 
	    specified only through the hour.
	    
	    If you only want to get a track mapped on 20 july 2005 from
	    10 am to 6pm, you should use this:
	    
	    gpsbabel -t \
		     -i gpx -f in.gpx \
		     -x track,start=2005072010,stop=2005072018 \
		     -o gpx -F out.gpx
	    
	PACK
	
            With this default option all tracks from input will be
            packed into one track. If tracks overlaps in time, the
            filter stops working.   To pack all the tracks together
	    into one track and give it a name, use this:

	    gpsbabel -t \
		     -i gpx -f in.gpx \
		     -x track,pack,title="ACTIVE LOG" \
		     -o gpx -F out.gpx
		     
	SPLIT
	
	    The input track will be split into several tracks 
	    depending on date of track points. If there is more 
	    than one track, use the pack option before before 
	    using this. 
  
	    To split a single tracks into separate tracks for each day
	    and name them, use this:
 
	    gpsbabel -t \
		     -i gpx -f in.gpx \
		     -x track,split,title="ACTIVE LOG # %Y%m%d" \
		     -o gpx -F out.gpx

	    If the input has multiple tracks, pack them together before
	    splitting them back apart per day thusly:
	    
	    gpsbabel -t \
		     -i gpx -f in.gpx \
		     -x track,pack,split,title="ACTIVE LOG # %D" \
		     -o gpx -F out.gpx

            Additionally you can add an interval to the split option.
            With this the track will be split if the time between two
            points is greater than this parameter. The interval must be
            numeric and can be int days, hours, minutes or seconds, 
	    expressed as one of the character "d", "h", "m", or "s".
	    If no trailing character is present, the units are assumed to
	    be in seconds.

            For example, to split a track based on an four hour interval, 
	    use this:

            gpsbabel -t \ 
			-i gpx -f in.gpx \ 
			-x track,pack,split=4h,title="LOG # %c" \ 
			-o gpx -F out.gpx

 	MERGE
 	    
 	    Merge puts all track points into one single track and
 	    sort them by time. Points with identical time stamp 
 	    will be dropped !!!
 	    
 	    If you want to merge tracks from different devices 
 	    but from same trip, use this:
 	    
 	    gpsbabel -t \
 		     -i gpx -f john.gpx \
 		     -i gpx -f doe.gpx \
 		     -x track,merge,title="COMBINED LOG" \
 		     -o gpx -F john_doe.gpx

    DISCARD

        This filter 'fixes' gps data by discarding points with a hdop
        and/or vdop over a set limit. If you give both the hdop and a
        vdop options, by default points that exceed EITHER are discarded
        (OR). This filter processes waypoints, tracks, and routes.

        HDOP (float)

            Points with a hdop exceeding the given value are discarded.

        VDOP (float)

            Points with a vdop exceeding the given value are discarded.

        HDOPANDVDOP

            Only useful if both hdop and vdop are given. Now logical AND
            is used, i.e. only points exceeding both given values are
            discarded.

            Example: gpsbabel \ 
		-i gpx -f in.gpx \
		-x discard,hdop=10,vdop=20,hdopandvdop \ 
		-o gpx -F out.gpx

        Contributed by Tobias Minich.
