Skip to main content

Module gpx

Module gpx 

Source
Expand description

GPX files, the GPS Exchange Format, holding the tracks a GPS receiver, a phone app or a mapping tool recorded, in version 1.0 or 1.1 of the format Topografix publishes.

GPX is XML. Its root element gpx states its version and the program that wrote it (creator), then holds waypoints (wpt), routes (rte, each a list of rtept) and tracks (trk). A track is a list of segments (trkseg), each a list of track points (trkpt):

<gpx version="1.1" creator="…" xmlns="http://www.topografix.com/GPX/1/1">
  <trk><name>Flight 7</name>
    <trkseg>
      <trkpt lat="35.2000120" lon="-97.1000340">
        <ele>402.0</ele><time>2031-07-14T17:04:04.000Z</time><sat>11</sat><hdop>0.8</hdop>
      </trkpt>
    </trkseg>
  </trk>
</gpx>

What the sources set. Topografix’s schemas, GPX 1.0 (topografix.com/GPX/1/0/gpx.xsd) and GPX 1.1 (topografix.com/GPX/1/1/gpx.xsd), and GPX 1.0’s manual (topografix.com/gpx_manual.asp). GPX 1.0’s schema holds types and no documentation, so the words quoted here are GPX 1.1’s schema’s; GPX 1.0’s manual says the same of each element it describes. A point’s lat and lon are in “Decimal degrees, WGS84 datum”, the latitude from −90 to 90 and the longitude from −180 to 180 (both schemas’ types: 1.1 leaves out 180 itself, 1.0 doesn’t; this reader takes 180, the same meridian as −180). Its ele is the “Elevation (in meters) of the point”, with no datum of its own. GPX 1.1’s schema opens with “all coordinates are relative to the WGS84 datum”, which could be read as heights above the WGS84 ellipsoid, but it doesn’t say so of ele, nor does the manual, and neither says whether a writer’s elevation is above that ellipsoid, above mean sea level or from a barometer. A point’s geoidheight is the geoid’s height above the WGS84 ellipsoid, “as defined in NMEA GGA message”. A point’s time is an XML Schema dateTime, and “Date and time in are in Univeral [sic] Coordinated Time (UTC), not local time!” sat is the “Number of satellites used to calculate the GPX fix”, hdop, vdop and pdop its dilutions of precision, and a fix of “none means GPS had no fix”. In GPX 1.0 a track point may also hold course, in “degrees, true”, and speed, in “meters per second” (the manual); GPX 1.1 dropped both. A track segment “holds a list of Track Points which are logically connected in order. To represent a single GPS track where GPS reception was lost, or the GPS receiver was turned off, start a new Track Segment for each continuous span of track data.”

Tracks and channels. A GPX file holds tracks of positions, not an altimeter’s record over time, so the record’s primary track is empty and every value is a channel, with a note, as the GPS logs’ decision, ADR-254 §2, has it. Each track segment is a GPS track, its channels named after its track’s name, or track if it has none; the segments of a track with several are numbered, <name> segment 2, by their place in the track, and a name already used gains (2), (3) …, so no two segments share a name:

ChannelQuantityFrom
<name> latitude, <name> longitudeQuantity::Latitude, Quantity::Longitudelat, lon
<name> elevationQuantity::Altitude, mele: an altitude whose datum the file doesn’t state
<name> satellitesQuantity::Numbersat
<name> HDOP, <name> VDOP, <name> PDOPQuantity::Numberhdop, vdop, pdop
<name> geoid heightQuantity::Distance, mgeoidheight: the geoid above the WGS84 ellipsoid, NMEA’s geoid separation
<name> speedQuantity::Speed, m/sGPX 1.0’s speed
<name> courseQuantity::Angle, ° from true northGPX 1.0’s course

A channel is there only if some point of its segment holds its element; a point that lacks it, or holds it empty, such as <ele/>, is a gap, NaN, the empty ones counted in a note. The rest of a point (magvar, fix, its names and descriptions, extensions, other namespaces’ elements, and a waypoint’s or route point’s geoidheight) is counted in a note and not read. The elevation is Quantity::Altitude, not Quantity::GnssAltitude, whose altitude is above mean sea level as the receiver states it: a GPX file states neither the datum nor the sensor, so only the rise from one point to another means what it says.

What ele most likely holds (sources read 2026-10-17 to 2026-10-23). A receiver’s NMEA GGA sentence gives the antenna’s altitude above mean sea level, the geoid, and the geoid’s separation from the WGS84 ellipsoid (gpsd’s NMEA notes, gpsd.gitlab.io/gpsd/NMEA.html; u-blox’s M10 interface description, UBX-21035062 R03, GGA alt, “Altitude above mean sea level”). Phones differ: Android’s Location.getAltitude() is above the WGS84 ellipsoid, iOS’s CLLocation.altitude above mean sea level, and a handheld with a barometer may write the barometer’s altitude. GPSLogger for Android wrote 7 of 10 GPX files with geoidheight opened on GitHub. Its sea-level option “subtracts the geoidheight from the reported altitude” (its FAQ, gpslogger.app), so with the option off it writes Android’s ellipsoidal height; in three such files on clear terms, ele sits above SRTM’s ground heights by about their geoidheight, and a fourth’s is too small to tell (issue #645, 2026-10-20). The rocketry trackers checked export KML, CSV or NMEA, not GPX, and their manuals that state a datum say mean sea level (Missile Works’ RTx/GPS manual, firmware 1.31; Featherweight’s Swift manual, 2026-04-10). One Eggfinder track saved as GPX by MapSphere reads 6.7 to 7.4 m below the pad’s terrain height as a sea-level height and 26 m above it as an ellipsoid’s, so it most likely holds the GGA altitude, with moderate confidence (a research note). So geoidheight doesn’t settle ele’s datum, and the reader’s note says which writer does what. Either datum is off by an offset that barely changes over one flight: it moves the pad’s elevation, not the height above the pad. A barometric ele would differ by an amount that grows with height.

Routes and waypoints are places marked or planned, not flown, so they are kept apart from the tracks, as figures the file states (Stated::figures), each in the file’s order: a waypoint’s waypoint <name> latitude, … longitude, … elevation and … time, and a route point’s route <name> point <n> latitude and so on, <name> the waypoint’s or the route’s name, or its place among the file’s waypoints or routes, waypoint 2, if it has none. A time is in seconds from the log’s zero, Quantity::Duration. No reading takes them for the flight.

Times. A point’s time is its time, in UTC: one that states an offset from UTC, such as -04:00, is moved to UTC; one that states no zone is read as UTC, as GPX 1.1’s schema and GPX 1.0’s manual say every time is, with a note counting them. The log’s zero is the first time the file gives a track point, or, with none, a waypoint or route point, and a note names it. A track point with no time keeps its place with its time a gap, NaN. Times within a track go forward, segment to segment: one that goes back is refused by name, as such a track isn’t one recording. Two tracks may run in any order, as a file holding two flights does. A second written 60, a leap second’s, reads as the next minute’s first, as in the KML reader; no sample holds one.

Refused by name. A document type declaration, so that no entity can expand, and a reference to an entity XML doesn’t define; a root that isn’t gpx, or whose namespace or version isn’t GPX 1.0’s or 1.1’s, or whose namespace and version disagree; a point with no lat or lon, or one off the globe (its latitude past ±90° or longitude past ±180°, once read to the nearest double); a value that isn’t the schema’s kind of number (ele and the rest are XML Schema decimals, written with no exponent; sat is a whole number); a course outside 0° to 360°; a point holding one of the elements read twice; a time that isn’t a date and time; and a time that goes back within a track. Each names what it found and its line: a point’s, or the declaration’s, the root’s, or the line where the nesting passes the bound (a file of too many nodes is refused at line 1, as the parser gives that refusal no place).

Hostile input. roxmltree parses the XML, with its default refusal of a document type declaration and a limit of MAX_NODES nodes. The parser descends the tree on the stack, so the text’s nesting is counted first, as the KML reader’s is (crate::kml), and a file nesting elements deeper than MAX_DEPTH is refused. At most MAX_TRACKS segments, MAX_POINTS track points and MAX_PLACES waypoints and route points are read, the rest counted in a note; names are cut to the length a note quotes, and the note listing what isn’t read names at most MAX_UNREAD_NAMES elements.

Where this comes from, and how far to trust it. The schemas and the manual as cited; no GPX reader was ported. No sample log in the project’s collection is a GPX file, so the reader is checked on invented files only, every value against gpxpy 1.6.2 (Apache-2.0), run as an outside reader (validation/oracles/gpx/gpxpy_read.py). One real rocket track, read for the research note above, points to a sea-level ele, with moderate confidence (one app, one pad). No rocket flight’s GPX with geoidheight has been seen, so the note on geoidheight rests on GPSLogger’s documentation and files, none of them a flight.

Constants§

MAX_DEPTH
The deepest the XML may nest its elements, as the KML reader’s bound (kml::MAX_DEPTH): roxmltree descends the tree on the stack, so the nesting is counted before the text is parsed. A track point’s extensions sit 5 deep (gpx, trk, trkseg, trkpt, extensions), an app’s own elements a few more.
MAX_NODES
The most XML nodes the parser builds for one file, so a file of many tiny elements can’t fill memory. A track point with its elevation, time, satellite count and three dilutions of precision is about 21 nodes, its whitespace included, so this holds some 190,000 such points, more than two days of a receiver writing once a second.
MAX_PLACES
The most waypoints and route points read from one file, together; past it, the rest are counted in a note. Each gives up to four figures.
MAX_POINTS
The most track points read from one file, over all its segments; past it, the rest are counted in a note.
MAX_TRACKS
The most track segments read from one file, each a track; past it, the rest are counted in a note.
MAX_UNREAD_NAMES
The most names of elements not read that the note listing them names; the rest are counted.

Functions§

read
Reads a GPX file’s tracks into a flight record, its waypoints and routes as figures it states.