-->

Note: This page describes the development version of GPSBabel. It may substantially differ from the latest released GPSBabel.

Include Only Points Inside Polygon (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 include an island or a hole, just append it to the main polygon.

# A square polygon with a triangular hole
41.0000       -85.0000
41.0000       -86.0000
42.0000       -86.0000
42.0000       -85.0000
41.0000       -85.0000
# The hole begins here
41.5000       -85.5000
41.6000       -85.5000
41.6000       -85.6000
41.5000       -85.5000

As with the arc filter, you define a polygon by giving the name of the file that contains it, using the file option.

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.

Example 4.1. Using the polygon filter

Suppose 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


Example 4.2. Using the polygon and arc filters to find points in or nearly in a polygon

Because the polygon and arc filters use the same file format, you can use them together to find all points that are "in or nearly in" a polygon. This can be useful if your waypoints or the boundaries of your polygon are not quite perfect, so you want to provide a buffer zone around it in case there are points nearby that should be in the polygon but aren't quite.

gpsbabel -i gpx -f points.gpx -x stack,push -x polygon,file=mycounty.txt -x stack,swap -x arc,file=mycounty.txt,distance=1k -x stack,pop,append -x duplicate,shortname -o gpx -F nearmycounty.gpx

This command makes a copy of the points, finds the ones that are in your your county, swaps that result with the copy of the original set of points, finds the ones from that set that are within 1 km of the border of the county, puts the two lists together, and then filters out any points that appear twice (This step is necessary because points inside the county but near the county line will be kept by both the polygon and the arc filter.)


file option

File containing vertices of polygon.

This option is required.

This option specifies the name of the file containing the polygon to use for filtering. The format of the file is as described above.

GPSBabel supports converting any route or track to a file usable by this filter; simply read it in the normal way and write it using the arc file format. Afterward, you will need to make sure that the first point and the last point in the file are the same, as the polygon filter depends on that. You can do so with any text editor.

exclude option

Exclude points inside the polygon.

When this option is specified, the usual sense of the polygon filter is reversed. That is, points that are inside the polygon are discarded while points that are further away are kept.