gpx(n)

🌸 gpx(n) — GPS eXchange Format (GPX) 🌸

okay bestie, welcome to the gpx(n) manual page, and honestly? it's giving "I just want to read my little GPS files" and I respect it so much. it's all about the GPS eXchange Format and pulling waypoints, tracks and routes out of it. let's go 💅

---

✨ NAME ✨

gpx — Extracts waypoints, tracks and routes from GPX files

like, that's the whole job. it extracts. waypoints, tracks, routes. from GPX files. iconic. 🦋

---

✨ 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

see how ?1.1? has question marks around it? that's the "optional, bestie, no pressure" notation. the 8.5 9 for Tcl is just saying which Tcl versions you can run this on. 🫶

---

✨ DESCRIPTION ✨

okay so this module parses and extracts waypoints, tracks, routes and metadata from a GPX (GPS eXchange) file. and the best part? both GPX version 1.0 and 1.1 are supported ✨ so you're not out here getting format-shamed. both eras of GPX get to eat. 🍓

---

✨ COMMANDS ✨

listen, this is the main character section. every command you get to call, and what it does. no skips, no skims. 💖

• ::gpx::Create gpxFilename ?rawXML? — this is the first command you call to process GPX data, periodt. it takes the GPX data from the rawXML parameter if that's present, or otherwise from the contents of gpxFilename, and it parses it using tdom. it hands you back a token value, and that token is what literally every other command needs. so don't lose it. 🔑
• ::gpx::Cleanup token — this procedure cleans up the resources tied to token. and bestie, I'm gonna say this with my whole chest: it is strongly recommended that you call this after you're done with a given GPX file. not calling it means memory doesn't get freed, and if your app calls ::gpx::Create enough times, that memory leak could cause a performance hit… or worse. 💀 so. cleanup. your. tokens.
• ::gpx::GetGPXMetadata token — returns a dictionary of the metadata associated with the GPX data identified by token. the format of that metadata dictionary is described down below in DATA STRUCTURES, but heads up: the keys version and creator will always be present. always. no exceptions. 👑
• ::gpx::GetWaypointCount token — returns the number of waypoints defined in the GPX data identified by token. just a number. a cute little number. ✨
• ::gpx::GetAllWaypoints token — returns a list of waypoints defined in the GPX data identified by token. (yes, the original says "returns the a list" — I'm keeping the typo's spirit alive because I love it, but you get the idea: it's a list of waypoints.) the format of each waypoint item is described below in DATA STRUCTURES. 📍
• ::gpx::GetTrackCount token — returns the number of tracks defined in the GPX data identified by token. count 'em up. 🛤️
• ::gpx::GetTrackMetadata token whichTrack — returns a dictionary of the metadata associated with track number whichTrack (1 based) in the GPX data identified by token. the metadata dictionary format is described below. note the 1-based thing — we're not doing zero-indexing here, bestie. 🎀
• ::gpx::GetTrackPoints token whichTrack — returns a list of track points comprising track number whichTrack (1 based) in the GPX data identified by token. (the original says "the format of the metadata dictionary is described below" here too — I'm passing that along verbatim in spirit.) 🧚
• ::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. metadata dictionary format = described below. same 1-based energy. 💜
• ::gpx::GetRoutePoints token whichRoute — returns a list of route points comprising route number whichRoute (1 based) in the GPX data identified by token. and again, the original says the metadata dictionary format 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 gets returned in a dictionary. the keys of that dictionary will be whatever optional GPX elements are present — so it's very much a "you get what your file gives you" situation, iykyk. 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
• the value for a link key will be a sub-dictionary with keys href and optionally text and type

so like, nesting is real here. dictionaries inside dictionaries. it's giving matryoshka but make it geo. 🪆

point item 📍

each item in a track or route list of points consists of a list of three elements:

1. latitude
2. longitude
3. metadata dictionary

latitude and longitude are decimal numbers. the metadata dictionary format is described above. and for points in a track, typically there will always be ele (elevation) and time metadata keys — so if you're expecting them and they're not there, that's the "typically" doing a lot of work, bestie. 🏔️⏰

---

✨ EXAMPLE ✨

here's a whole little session, in all its % prompt glory. copy it exactly, it's precious:

% 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

look at that last line. ::gpx::Cleanup $token. the cleanup is right there in the example — that's the universe telling you to do it. do it. 🙏

---

✨ REFERENCES ✨

the receipts, the sources, the "go read these if you want the deep lore":

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)

---

✨ AUTHOR ✨

Keith Vetter 👑 — thank you for your service.

---

✨ BUGS, IDEAS, FEEDBACK ✨

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. that's just how software is, no cap. so please report such things in the category gpx of the Tcllib Trackers (http://core.tcl.tk/tcllib/reportlist). 💀

also please report any ideas for enhancements you may have for either the package and/or the documentation. we love ideas. ideas are the vibe. 🌈

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

and note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. yes, that exact button. the left-most one. don't overthink it, bestie. 🫶

---

✨ KEYWORDS ✨

gps, gpx 🌍

---

✨ CATEGORY ✨

File formats 📁

---

✨ COPYRIGHT ✨

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

---

okay that's the whole page!! 💖 this was tcllib version 1.1, and the page itself is gpx(n) — so if you see those two floating around in your terminal, that's us. now go forth, parse your GPX files, and clean up your tokens. mwah. 💅✨