1gpx(n)                     GPS eXchange Format (GPX)                    gpx(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       gpx - Extracts waypoints, tracks and routes from GPX files
9

SYNOPSIS

11       package require Tcl  8.5
12
13       package require gpx  ?0.9?
14
15       ::gpx::Create gpxFilename ?rawXML?
16
17       ::gpx::Cleanup token
18
19       ::gpx::GetGPXMetadata token
20
21       ::gpx::GetWaypointCount token
22
23       ::gpx::GetAllWaypoints token
24
25       ::gpx::GetTrackCount token
26
27       ::gpx::GetTrackMetadata token whichTrack
28
29       ::gpx::GetTrackPoints token whichTrack
30
31       ::gpx::GetRouteCount token
32
33       ::gpx::GetRouteMetadata token whichRoute
34
35       ::gpx::GetRoutePoints token whichRoute
36
37______________________________________________________________________________
38

DESCRIPTION

40       This  module parses and extracts waypoints, tracks, routes and metadata
41       from a GPX (GPS eXchange) file. Both GPX version 1.0 and 1.1  are  sup‐
42       ported.
43

COMMANDS

45       ::gpx::Create gpxFilename ?rawXML?
46              The  ::gpx::Create  is  the  first command called to process GPX
47              data. It takes the GPX data from either the rawXML parameter  if
48              present or from the contents of gpxFilename, and parses it using
49              tdom. It returns a token value that is used  by  all  the  other
50              commands.
51
52       ::gpx::Cleanup token
53              This procedure cleans up resources associated with token.  It is
54              strongly recommended that you call this function after  you  are
55              done  with a given GPX file.  Not doing so will result in memory
56              not being freed, and if  your  app  calls  ::gpx::Create  enough
57              times, the memory leak could cause a performance hit...or worse.
58
59       ::gpx::GetGPXMetadata token
60              This  procedure  returns a dictionary of the metadata associated
61              with the GPX data identified by token.  The format of the  meta‐
62              data dictionary is described below, but keys version and creator
63              will always be present.
64
65       ::gpx::GetWaypointCount token
66              This procedure returns the number of waypoints  defined  in  the
67              GPX data identified by token.
68
69       ::gpx::GetAllWaypoints token
70              This  procedure  returns  the a list of waypoints defined in the
71              GPX data identified by token. The format of each  waypoint  item
72              is described below.
73
74       ::gpx::GetTrackCount token
75              This  procedure  returns the number of tracks defined in the GPX
76              data identified by token.
77
78       ::gpx::GetTrackMetadata token whichTrack
79              This procedure returns a dictionary of the  metadata  associated
80              track  number whichTrack (1 based) in the GPX data identified by
81              token.  The format of the metadata dictionary is  described  be‐
82              low.
83
84       ::gpx::GetTrackPoints token whichTrack
85              The  procedure  returns  a list of track points comprising track
86              number whichTrack (1 based) in the GPX data identified by token.
87              The format of the metadata dictionary is described below.
88
89       ::gpx::GetRouteCount token
90              This  procedure  returns the number of routes defined in the GPX
91              data identified by token.
92
93       ::gpx::GetRouteMetadata token whichRoute
94              This procedure returns a dictionary of the  metadata  associated
95              route  number whichRoute (1 based) in the GPX data identified by
96              token.  The format of the metadata dictionary is  described  be‐
97              low.
98
99       ::gpx::GetRoutePoints token whichRoute
100              The  procedure  returns  a list of route points comprising route
101              number whichRoute (1 based) in the GPX data identified by token.
102              The format of the metadata dictionary is described below.
103

DATA STRUCTURES

105       metadata dictionary
106              The metadata associated with either the GPX document, a track, a
107              route, a waypoint, a track point or route point is returned in a
108              dictionary.  The  keys  of  that dictionary will be whatever op‐
109              tional GPX elements are present. The value for each key  depends
110              on the GPX schema for that element. For example, the value for a
111              version key will be a string, while for a link  key  will  be  a
112              sub-dictionary with keys href and optionally text and type.
113
114       point item
115              Each  item in a track or route list of points consists of a list
116              of three elements: latitude, longitude and metadata  dictionary.
117              Latitude and longitude are decimal numbers. The metadata dictio‐
118              nary format is described above. For points in a track, typically
119              there will always be ele (elevation) and time metadata keys.
120

EXAMPLE

122              % set token [::gpx::Create myGpxFile.gpx]
123              % set version [dict get [::gpx::GetGPXMetadata $token] version]
124              % set trackCnt [::gpx::GetTrackCount $token]
125              % set firstPoint [lindex [::gpx::GetTrackPoints $token 1] 0]
126              % lassign $firstPoint lat lon ptMetadata
127              % puts "first point in the first track is at $lat, $lon"
128              % if {[dict exists $ptMetadata ele]} {
129                   puts "at elevation [dict get $ptMetadata ele] meters"
130                }
131              % ::gpx::Cleanup $token
132
133

REFERENCES

135       [1]    GPX: the GPS Exchange Format (http://www.topografix.com/gpx.asp)
136
137       [2]    GPX      1.1      Schema      Documentation      (http://www.to
138              pografix.com/GPX/1/1/)
139
140       [3]    GPX 1.0 Developer's  Manual  (http://www.topografix.com/gpx_man
141              ual.asp)
142

AUTHOR

144       Keith Vetter
145

BUGS, IDEAS, FEEDBACK

147       This  document,  and the package it describes, will undoubtedly contain
148       bugs and other problems.  Please report such in the category gpx of the
149       Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please also
150       report any ideas for enhancements  you  may  have  for  either  package
151       and/or documentation.
152
153       When proposing code changes, please provide unified diffs, i.e the out‐
154       put of diff -u.
155
156       Note further that  attachments  are  strongly  preferred  over  inlined
157       patches.  Attachments  can  be  made  by  going to the Edit form of the
158       ticket immediately after its creation, and  then  using  the  left-most
159       button in the secondary navigation bar.
160

KEYWORDS

162       gps, gpx
163

CATEGORY

165       File formats
166
168       Copyright (c) 2010, Keith Vetter <kvetter@gmail.com>
169
170
171
172
173tcllib                                0.9                               gpx(n)
Impressum