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 .

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.

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

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.

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.

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

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

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

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.

This filter is designed to solve advanced problems that involve shuffling multiple lists of waypoints.  It has three distinct sets of suboptions:

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

'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

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
 

( !!! This filter always drops empty tracks !!! )

The track filter is a tool for manipulating track lists.

The following options are available:

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

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

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

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

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 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

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.

Points with a hdop exceeding the given value are discarded.

Points with a vdop exceeding the given value are discarded.

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.