Include Only Points Within Distance of Arc (arc)
Prev | Chapter 4. Data Filters | Next

## 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. The output is reordered by distance to the arc, closest points first.

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

The units may be specified by appending a suffix to the supplied number:

'm' for meters, e.g. 3500.0m
'ft' or 'feet' for feet, e.g. 11483ft
'k' or 'km' for kilometers, e.g 3.5000km
'nm' for nautical miles, e.g. 1.8898nm
'mi' for miles, e.g. 2.1748mi
'fa' for fathoms, e.g. 1913.82fa

If no units are specified, the units are assumed to be 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 either the `rte` or `trk` option the altitude and creation_time of the projected waypoints are updated, if possible, by interpolation from the route or track data.

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

Prev | Up | Next
Include Only Points Inside Polygon (polygon) | Home | Include Only Points Within Radius (radius)