GPX Editor

Abstract

GPX Editor is a single-page tool for inspecting and editing GPX track files. Parse, render, edit, and export all happen client-side via the browser's DOMParser, Canvas 2D, and Blob APIs — no external JavaScript libraries, no tile-map library, no build step. PHP is used only for the optional upload and save-to-server endpoints; the core viewer/editor flow works without ever contacting the server. The tool targets runners, cyclists, and photographers who want to clean up GPS recordings (drop bad points, smooth elevation noise, split sessions, re-export) without uploading their tracks to a third party.

Data Sources

Known limitations

• The parser is namespace-agnostic but only consumes the GPX 1.0 / 1.1 core schema. Garmin extensions (heart rate, cadence, temperature) are preserved by the renderer as-is in memory but stripped on export — the serialiser only emits standard GPX 1.1.
• File size is capped at 10 MB both client-side (early reject) and server-side (PHP upload.php / save.php).
• Multi-track files (more than one <trk>) are parsed and rendered, but the editor UI talks about "the track" in the singular. Per-track editing works; per-track navigation in the sidebar is a known gap.
• The renderer uses Mercator projection. Latitudes outside ±85° clamp to the limit; trans-polar tracks will render incorrectly.

Methodology

1. Module pattern over ES modules

Every file attaches to a global window.GPXEditor namespace and is loaded via plain <script> tags with a per-request CSP nonce. ES module import was rejected for two reasons: it forces strict MIME-type handling for .js from the PHP server (extra config), and it triggers CORS preflights when the same files are served from a simple file:// dev open. Module load order is fixed in index.php: app → parser → renderer → editor → export, then GPXEditor.boot().

// All modules follow this pattern
(function (GPXEditor) {
  'use strict';
  const renderer = {};
  // … implementation …
  GPXEditor.renderer = renderer;
})(window.GPXEditor);

2. Namespace-agnostic GPX parsing

GPX 1.0 uses http://www.topografix.com/GPX/1/0; GPX 1.1 uses http://www.topografix.com/GPX/1/1. getElementsByTagNameNS would force a choice; getElementsByTagName is case-sensitive on XML documents. The parser instead walks element.children and filters by localName, which works for either namespace and any extension namespace, while being lazily evaluated via generator functions:

function* childrenByLocalName(el, local) {
  if (!el) return;
  for (const c of el.children) if (c.localName === local) yield c;
}

// Metadata also lives in two different places between 1.0 and 1.1
function parseMetadata(root) {
  const md  = firstChild(root, 'metadata');  // 1.1
  const src = md || root;                    // 1.0 falls back to <gpx>
  …
}

Invalid points (missing or non-finite lat/lon) throw rather than silently dropping. Silent drop was tried first; it masked a real bug in a test fixture by emitting a track that looked right but was missing a leg.

3. Canvas Mercator renderer

The map view is a single <canvas>. Coordinates are projected to Mercator radians (range ±π); a separate continuous state.view.zoom stores pixels-per-radian. The same coordinate system is used for the tile layer added later, so the underlying maths did not need to change when the basemap was bolted on. World-to-screen and screen-to-world are pure functions:

function worldToScreen(mx, my) {
  const v = viewport(), s = GPXEditor.state.view;
  return {
    x: v.w / 2 + (mx - s.panX) * s.zoom,
    y: v.h / 2 - (my - s.panY) * s.zoom, // y inverted: north is up
  };
}

Auto-fit on first paint computes the bbox in Mercator space and chooses a zoom that fits both axes inside the canvas with 40 px padding. Subsequent paints respect the user's pan / wheel-zoom / pinch-zoom state.

4. Tile basemap (bolted on after v1.0)

The original spec called for "no tile map". First feedback from a real user was that an isolated red polyline on black was unreadable. The fix re-uses the existing Mercator code: a chosen integer tile zoom z = round(log₂(stateZoom · 2π / 256)) selects a z/x/y from CARTO Dark Matter, the tile's world bounds are converted through worldToScreen, and the tile image is drawn with rounded integer coordinates so adjacent tiles butt without seams.

An LRU tile cache (max 512 entries) keeps memory bounded. Loaded tiles trigger a coalesced redraw via requestAnimationFrame so a burst of arrivals does not paint 16 times in 16 ms. The CSP img-src was widened to https://*.basemaps.cartocdn.com for this; everything else remained self.

5. Pub/sub event bus

Modules do not call each other directly. app.js exposes GPXEditor.events.on / off / emit and the modules subscribe to the events they care about (data:loaded, data:edited, selection:changed, view:resize). This keeps the renderer ignorant of the editor and vice versa, and made the bolted-on basemap a strictly additive change.

6. Edit operations

Three categories of mutation, all in editor.js:

• Selection & deletion — click any track point, waypoint, or route point on the canvas; the sidebar exposes a typed editor and a delete button. Index re-anchoring after deletion is explicit: when point i is removed, the new selection becomes min(i, len-1) so the user can hold delete to trim a tail.
• Segment split — shift-click a second point in the same segment to mark a split anchor, then Split. The point at the higher index becomes the first sample of the new segment.
• Elevation smoothing — centred moving average with configurable window (3 / 5 / 10). Operates per-segment so split boundaries are respected. Edge points use a shrunken window rather than clipping, to avoid cliff-edges at boundaries.

7. GPX serialisation

The exporter emits GPX 1.1 with the standard schemaLocation declared so validators can verify the output. Element order matches the schema (ele → time → name → desc) because some third-party parsers are strict about it. Track points without elevation and without time collapse to a self-closing one-liner, which shaves substantial bytes on big files. Numeric formatting trims trailing zeros (6 decimal places of latitude / longitude is sub-metre).

<trk>
  <name>Sample Loop</name>
  <trkseg>
    <trkpt lat="49.611" lon="6.131">
      <ele>300.0</ele>
      <time>2026-05-23T08:00:00Z</time>
    </trkpt>
    <trkpt lat="49.612" lon="6.132"/>
  </trkseg>
</trk>

8. PHP backend (optional)

Two endpoints, both with a layered validation chain:

1. upload.php — method → file presence → size → extension → finfo MIME → magic bytes (<?xml) → simplexml_load_string → <gpx> root. Each step short-circuits on failure with a distinct HTTP status code (4xx / 5xx).
2. save.php — same validation against the JSON request body, plus an atomic-ish stage-and-rename write.

The persisted filename is always a server-generated UUID; the client-supplied name is logged-style only. The uploads/ directory ships with an .htaccess that disables directory listing, strips PHP / CGI handlers, forces Content-Disposition: attachment, and denies any file whose extension is not .gpx.

9. CSP & nonces

Every <script> tag carries a per-request nonce generated by random_bytes(16) in index.php. The CSP is default-src 'none'; script-src 'self' 'nonce-…'; img-src 'self' data: https://*.basemaps.cartocdn.com (basemap); everything else self. strict-dynamic is intentionally omitted because modules load statically.

Stack & Tooling

• Languages: HTML5, CSS3 (custom properties), vanilla JavaScript ES2020+, PHP 8.1+
• Libraries: none — not Leaflet, not jQuery, not anything
• Map tiles: CARTO Dark Matter (free, no key)
• Fonts: JetBrains Mono self-hosted via /fonts/fonts.css — substituted for the IBM Plex Mono originally specified, for consistency with the rest of the lab and zero external font requests
• Build tools: none — source is production
• PHP extensions: simplexml, fileinfo, json — all default in a stock 8.x
• Browser targets: Chrome 110+, Firefox 115+, Safari 16+

Key Observations & Limitations

What works

• Namespace-agnostic parsing handles every GPX file thrown at it so far (Garmin, Strava export, Komoot, RideWithGPS, OpenTracks).
• The Mercator code was generic enough to host a tile basemap without refactoring.
• Pub/sub keeps each module under ~500 lines and independently testable.
• Layered backend validation (extension + MIME + magic bytes + SimpleXML + root) catches obvious bad uploads without leaking parser internals.

Known gaps

• Multi-track navigation in the sidebar — today a track-of-tracks file has no per-track selector.
• GPX extensions (HR, cadence, power) are dropped on export. Round-tripping fitness data is a separate project.
• No undo / redo. Deletion and smoothing are immediate. The exporter is the safety net — re-export and you have a checkpoint.
• The elevation profile is drawn fresh on every redraw. For very long tracks (10k+ points) this is fine on desktop but mildly janky on mobile.

Possible future directions

• Multi-track sidebar with per-track visibility toggles.
• Optional GPX 1.1 extension passthrough (preserve unknown child elements verbatim).
• Undo / redo stack on the editor mutations.
• Track simplification (Douglas-Peucker) as a fourth tool alongside smoothing and split.
• Optional offline tile cache via Service Worker, for editing GPX files in the field with no network.