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:
| Channel | Quantity | From |
|---|---|---|
<name> latitude, <name> longitude | Quantity::Latitude, Quantity::Longitude | lat, lon |
<name> elevation | Quantity::Altitude, m | ele: an altitude whose datum the file doesn’t state |
<name> satellites | Quantity::Number | sat |
<name> HDOP, <name> VDOP, <name> PDOP | Quantity::Number | hdop, vdop, pdop |
<name> geoid height | Quantity::Distance, m | geoidheight: the geoid above the WGS84 ellipsoid, NMEA’s geoid separation |
<name> speed | Quantity::Speed, m/s | GPX 1.0’s speed |
<name> course | Quantity::Angle, ° from true north | GPX 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):roxmltreedescends the tree on the stack, so the nesting is counted before the text is parsed. A track point’sextensionssit 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.