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