The primary immediate application of this system is to display, superimposed on a base map, waypoints (locations with descriptions) collected with a Global Positioning System (GPS) receiver.
Accordingly, the first step is to record GPS waypoints and enter these data into a file. Such files will be input to the steps described in later sections.
Waypoints are organized into transects that record the order in which the locations were visited. This is important to give meanings to terms like “left” and “ahead”, which refer to the direction of travel with the GPS. Each transect has a name that can be used for loading it into the display applications.
When taking GPS waypoints in the field, you will need to record:
The coordinates of the waypoint. Currently, the program supports latitude and longitude coordinates. You can use any of these formats: degrees with decimal (e.g., 33.98253°), whole degrees and minutes with decimal (e.g., 33° 58.95'), or degrees, minutes, and seconds with optional decimal (e.g., 33° 58' 57" or 33° 58' 57.1"). Support for UTM (Universal Transverse Mercator) coordinates may be added in the future.
A brief description of what is at that waypoint. This isn't mandatory, but in most cases you'll want to provide it so that users can request the description of a point displayed on a map and get back something like “End of Forest Road 505” or “Abandoned water well for the Rienhardt Ranch.”
You may wish to record elevations as well. GPS units do not provide very good elevations (50 feet is a typical error), but they may be sufficient for your purposes. More accurate values from barometric or other measurements may be available, and elevations interpolated from topographic map contours can always be added to the data files later.
A simple text editor suffices for creating the raw file of waypoints. The format of this file is optimized for rapid entry. A later step (see Preparing the XML waypoint file below) checks this file for validity and transforms it to the XML-based format that is used by later processing steps.
Here is an fragment of a waypoint file:
!-- ! NM: Magdalena Mts: Copper Canyon Road !-- 340127n 1070759w Magdalenas: Copper Cyn x N. Fork Rds ....25n ...0804w Copper Cyn Rd: bends L across streambed ~6980' ....06n .....25w Sign `Copper Cyn Tr. No. 10', fork: L=mines, R=trail ....04n .....27w Copper Cyn Rd: gate to private inholding, ~7120'
The first three lines are comments. Lines starting with a bang (!) character are ignored.
Each of the remaining lines specifies a waypoint. The fourth line shown above gives the location as 34° 01' 27" N. Lat, 107° 07' 59" W. Long. You can use a number of different formats to enter coordinates; see the section above on flexible angle format.
The remainder of the line is the description.
Because the degrees don't change through this set, the program allows you to use period (.) characters at the beginning of a coordinate value to mean “copy the value from the corresponding position on the previous line.” So the first four characters of “....25n” and the first three characters of “...0804” are copied from the previous values, giving effective coordinates of “340125n 1070804”. Similarly, the next line is the equivalent of “340106n 1070825w”.
A script called makeway is used to translate the raw waypoint file, described in the previous section, to an XML-based form. The XML format has the advantage that it is easier for programs to read and use. It also allows you to use an XML file editor (such as the XML editing mode in emacs) to maintain and enhance the waypoint data after its initial entry.
To run this program:
makeway <raw-file >out-file.xml
where raw-file is the name of the raw waypoint file created as described above, and out-file.xml is the file to be created.
Once the file is built, you will need to edit the XML file in order to break the contents up into “routes” by enclosing sets of <pt> elements within a <route name="route-name id="route-id">...<//route> element. Later steps in this processing chain (described below) will allow you to display whole waypoint files on a base map, and the route name and ID elements will allow you to select only certain routes for display.
To continue the example in the preceding section, here is the start of the XML that might result from the input example, with a <route> element added by hand, naming these points as part of the Copper Canyon route (ID copper):
<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE waypoint-set SYSTEM "waypoints.dtd"> <!-- $Revision: 1.27 $ $Date: 2006/04/26 18:47:55 $ !--> <waypoint-set> <route name="Magdalenas: Copper Canyon" id="copper"> <pt latd='34' latm='01' lats='27' ns='n' lond='107' lonm='07' lons='59' ew='w' mapdatum='WGS-84' >Magdalenas: Copper Cyn x N. Fork Rds</pt> <pt latd='34' latm='01' lats='25' ns='n' lond='107' lonm='08' lons='04' ew='w' mapdatum='WGS-84' >Copper Cyn Rd: bends L across streambed ~6980'</pt> ... </route> </waypoint-set>