Include Only Points Within Distance of Arc (arc)

This filter keeps or removes waypoints 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. Optionally, it can move each non-deleted waypoint over the closest segment of the arc.

The arc may defined in a file whose name must be provided with the file, or the tracks or routes that have already been read. 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 may 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.

Example 4.3. Using the arc filter

Assuming the arc above is in a file called lima_rd.txt, the following command line would include only points within one mile of the section of Lima Road covered by the arc.

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


file option

File containing vertices of arc.

This option specifies the name of the file containing the arc 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.

rte option

Route(s) are vertices of arc.

When this option is specified the routes contains the vertices of the arc. If there are several routes then it is assumed that there is a gap between each of them.

trk option

Track(s) are vertices of arc.

When this option is specified the tracks contains the vertices of the arc. If there are several tracks then it is assumed that there is a gap between each of them.

distance option

Maximum distance from arc.

This option is not required, but if it is not specified the distance defaults to zero miles, which isn't very useful.

This option specifies the maximum distance a point may be from the arc without being discarded. Points that are closer to the arc are kept, while points that are further away are discarded.

Distances may be specified in miles (3M) or kilometers (5K). If no units are specified, the distance is assumed to be in miles.

exclude option

Exclude points close to the arc.

When this option is specified, the usual sense of the arc filter is reversed. That is, points that are closer than distance are discarded while points that are further away are kept.

points option

Use distance from vertices not lines.

When this option is specified, only points that are within the specified distance of one of the vertices of the arc are kept. This differs from the normal mode of operation in that in the normal mode, points that are close to the lines between points are also kept.

This option makes the arc filter act like a multi-point version of the radius filter.

project option

Move waypoints to its projection on lines or vertices.

When this option is specified, each non deleted waypoint is moved over the closest segment, or over the nearest point if points option is used.

With rte and trk optinos, if is possible, altitude, creation_time and microsecond fields of waypoints are updated by interpolation.

This is most useful if you are trying to obtain the closest points in a road to some places. Or if you want to know the step times on some places over the tracks. Also to transform waypoints in Garmin course points (see gtrnctr and garmin format).