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

Save and restore waypoint lists (stack)

This filter is designed to solve advanced problems that involve shuffling multiple lists of waypoints, tracks, or routes.

The stack filter can be used to save the current state of the entire collection of data. That state is placed on top of a stack of collections, so you can simultaneously have as many stored collections of data as you can fit in your computer's memory.

The stack filter 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

push option

Push waypoint list onto stack.

This is one of three "primary" options to the stack filter.

When this option is specified, the current state is pushed onto the top of the stack. By default, the current state is then cleared, but the copy option can be used to cause it to be saved.

pop option

Pop waypoint list from stack.

This is one of three "primary" options to the stack filter.

This option "pops" the collection of data from the top of the stack. By default, the saved state replaces the current state, but see the discard and append options for alternatives.

swap option

Swap waypoint list with <depth> item on stack.

This is one of three "primary" options to the stack filter.

When this option is specified, the current state is swapped with a saved state from the stack. By default, it is swapped with the top of the stack, but the depth can be used to specify a different saved state.

copy option

(push) Copy waypoint list.

This option is only valid when used with the push option. When this option is specified, a copy of the current state is pushed onto the stack but the current state is left unchanged. Otherwise, the push operation clears the current data collection.

append option

(pop) Append list.

This option is only valid in conjunction with the pop. When it is specified, the topmost collection of data from the stack is appended to the current collection of data.

discard option

(pop) Discard top of stack.

This option is only valid when used with the pop option. When this option is specified, the popped state is discarded and the current state remains unchanged.

replace option

(pop) Replace list (default).

This option is only valid when used with the pop option. This is the default behavior of the pop option, so you should never need to specify it, but it is included for the sake of readability. When this option is specified, the popped state replaces the current state.

depth option

(swap) Item to use (default=1).

This option is only valid when used along with the swap option. If specified, it indicates which item on the stack should be swapped with the current state. The default value is 1, which corresponds to the top of the stack.