gpx(3tcl)

💖 gpx — the manual page, but make it a group chat 💖

okay so bestie, welcome to gpx(3tcl), straight out of the GPS eXchange Format (GPX) corner of the manual. this is the page that teaches you how to pull waypoints, tracks and routes out of GPX files with Tcl, and honestly? it's giving main character energy. let's go 🦋

---

✨ NAME ✨

gpx — extracts waypoints, tracks and routes from GPX files. that's the whole job. no cap. 💅

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require gpx ?1.1?

::gpx::Create gpxFilename ?rawXML?

::gpx::Cleanup token

::gpx::GetGPXMetadata token

::gpx::GetWaypointCount token

::gpx::GetAllWaypoints token

::gpx::GetTrackCount token

::gpx::GetTrackMetadata token whichTrack

::gpx::GetTrackPoints token whichTrack

::gpx::GetRouteCount token

::gpx::GetRouteMetadata token whichRoute

::gpx::GetRoutePoints token whichRoute

look at that lineup. twelve little commands, all standing in formation, all iconic. 🎀

---

🫶 DESCRIPTION 🫶

so this module parses and extracts waypoints, tracks, routes and metadata from a GPX (GPS eXchange) file. and bestie, it's not picky — both GPX version 1.0 and 1.1 are supported. both. it ate. 🔥

---

👑 COMMANDS 👑

here's the whole roster, one by one, no skipping, i promise.

• ::gpx::Create gpxFilename ?rawXML? — this is the very first command you call to process GPX data, so like… start here. it grabs the GPX data from the rawXML parameter if you passed one, otherwise it reads the contents of gpxFilename, and it parses all of that using tdom. what does it hand back? a token value, which every single other command in this page needs. the token is the moment, honestly.
• ::gpx::Cleanup token — this one cleans up the resources tied to token. and listen, i'm not being dramatic here, it is strongly recommended that you call this once you're done with a given GPX file. skip it and memory does not get freed, and if your app calls ::gpx::Create enough times, that memory leak could cause a performance hit… or worse. so like, clean up after yourself. periodt. 💀
• ::gpx::GetGPXMetadata token — returns a dictionary of the metadata attached to the GPX data identified by token. the format of that metadata dictionary is described further down, but heads up: the keys version and creator will always be present. always always. 💖
• ::gpx::GetWaypointCount token — returns the number of waypoints defined in the GPX data identified by token. a number. that's it, that's the tea. ✨
• ::gpx::GetAllWaypoints token — returns the a list of waypoints defined in the GPX data identified by token. (yes, "the a list", we're keeping it, it's part of the vibe now 😭). the format of each waypoint item is described below. 🎀
• ::gpx::GetTrackCount token — returns the number of tracks defined in the GPX data identified by token.
• ::gpx::GetTrackMetadata token whichTrack — returns a dictionary of the metadata associated with track number whichTrack (1 based, so the first track is 1, not 0, don't @ me) in the GPX data identified by token. the format of the metadata dictionary is described below.
• ::gpx::GetTrackPoints token whichTrack — returns a list of track points comprising track number whichTrack (1 based) in the GPX data identified by token. the format of the metadata dictionary is described below. 🦋
• ::gpx::GetRouteCount token — returns the number of routes defined in the GPX data identified by token.
• ::gpx::GetRouteMetadata token whichRoute — returns a dictionary of the metadata associated with route number whichRoute (1 based) in the GPX data identified by token. the format of the metadata dictionary is described below.
• ::gpx::GetRoutePoints token whichRoute — returns a list of route points comprising route number whichRoute (1 based) in the GPX data identified by token. the format of the metadata dictionary is described below. 🌈

---

🧚 DATA STRUCTURES 🧚

metadata dictionary

the metadata associated with either the GPX document, a track, a route, a waypoint, a track point or route point comes back as a dictionary. the keys of that dictionary will be whatever optional GPX elements are present — so it's not a fixed shape, it's a vibe check against the schema. and the value for each key depends on the GPX schema for that element. for example: the value for a version key will be a string, while for a link key it'll be a sub-dictionary with keys href and optionally text and type. nested dictionaries, we love to see it. 💅

point item

each item in a track or route list of points is itself a list of three elements: latitude, longitude and a metadata dictionary. latitude and longitude are decimal numbers. the metadata dictionary format is the one described above. and for points in a track, typically there will always be ele (elevation) and time metadata keys. so if you were wondering where the elevation went — it's in there. 🏔️

---

⭐ EXAMPLE ⭐

here's the little glow-up in action, copy it exactly bestie:

% set token [::gpx::Create myGpxFile.gpx]
% set version [dict get [::gpx::GetGPXMetadata $token] version]
% set trackCnt [::gpx::GetTrackCount $token]
% set firstPoint [lindex [::gpx::GetTrackPoints $token 1] 0]
% lassign $firstPoint lat lon ptMetadata
% puts "first point in the first track is at $lat, $lon"
% if {[dict exists $ptMetadata ele]} {
     puts "at elevation [dict get $ptMetadata ele] meters"
  }
% ::gpx::Cleanup $token

see how it ends with ::gpx::Cleanup $token? yeah. do that. every time. 🫶

---

📚 REFERENCES 📚

1. GPX: the GPS Exchange Format (http://www.topografix.com/gpx.asp)
2. GPX 1.1 Schema Documentation (http://www.topografix.com/GPX/1/1/)
3. GPX 1.0 Developer's Manual (http://www.topografix.com/gpx_manual.asp)

three references, all linked, all sacred. go read them if you want the lore. 🌸

---

💜 AUTHOR 💜

Keith Vetter — the author. we stan. 👑

---

🐛 BUGS, IDEAS, FEEDBACK 🐛

ngl, this document, and the package it describes, will undoubtedly contain bugs and other problems. that's just how it is, no shade. so please report such things in the category gpx of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. and if you've got ideas for enhancements — for the package, for the documentation, either one, both, whatever — report those too. we want them. 💖

when you're proposing code changes, please provide unified diffs, i.e. the output of diff -u.

also note, bestie: attachments are strongly preferred over inlined patches. you can attach stuff by going to the Edit form of the ticket immediately after creating it, and then using the left-most button in the secondary navigation bar. that's the move. 🎀

---

🔑 KEYWORDS 🔑

gps, gpx

---

🗂️ CATEGORY 🗂️

File formats

---

⚖️ COPYRIGHT ⚖️

Copyright (c) 2010, Keith Vetter <kvetter@gmail.com>

---

and that's the whole page, bestie!! 🎉 this one came from tcllib, version 1.1, and it's filed under gpx(3tcl) — that's the manual name and the version, all wrapped up in a little bow for you. now go forth and parse some GPX files. slay. 💅✨🦋