GPXDocument | AIUI | Rokid

GPXDocument reads, creates, and edits GPX route data. Add start, end, waypoint, and track points in memory, then export the result as GPX XML for a map component or file.

GPXDocument

GPXDocument reads, creates, and edits GPX route data. Add start, end, waypoint, and track points in memory, then export the result as GPX XML for a map component or file.

Create a Route

GPXDocument is available globally and as an export from the built-in gpx module:

import { GPXDocument } from 'gpx';

const route = new GPXDocument();

route.setStartPoint({
  latitude: 30.2741,
  longitude: 120.1551,
  name: 'Start',
});

route.appendTrackPoint({
  latitude: 30.2765,
  longitude: 120.1582,
  elevation: 18,
  time: new Date().toISOString(),
});

route.setEndPoint({
  latitude: 30.2792,
  longitude: 120.1618,
  name: 'Finish',
});

bounds calculates the minimum and maximum coordinates across the route so a map can choose a suitable viewport.

Read Existing GPX

The constructor, GPXDocument.from(), and GPXDocument.parse() accept a GPX XML string, Blob, ArrayBuffer, typed array, or another GPXDocument:

const response = await fetch('/assets/morning-run.gpx');
const route = GPXDocument.parse(await response.arrayBuffer());

console.log(route.bounds);

Invalid GPX input throws an exception. Use try...catch when reading external data.

Export and Display a Route

toString() returns GPX XML text that can be passed to the data property of <map-gpx>:

export default {
  data: {
    routeGpx: '',
  },
  onLoad() {
    const route = new GPXDocument();
    route.appendTrackPoint({ latitude: 30.2741, longitude: 120.1551 });
    route.appendTrackPoint({ latitude: 30.2792, longitude: 120.1618 });

    this.setData({ routeGpx: route.toString() });
  },
};
<map style="width: 320px; height: 320px;">
  <template slot="overlays">
    <map-gpx data="{{ routeGpx }}" />
  </template>
</map>

Use toBlob() when the result needs to be passed or saved as a binary object. The returned MIME type is application/gpx+xml.

Input must contain one complete <gpx>...</gpx> root. Truncated XML, route fragments without a root, multiple GPX roots, and mismatched closing tags throw errors. Do not treat these inputs as empty routes.

API Reference

new GPXDocument(input?)

Creates an empty GPX document or a document from existing input. GPXDocument is both a global class and a named export of the gpx module.

GPXDocument.from(input) / GPXDocument.parse(input)

Creates a GPXDocument from existing content. Both methods behave the same way.

input typeDescription
stringGPX XML text.
BlobA blob containing GPX data.
ArrayBuffer / BufferSourceBinary GPX data.
GPXDocumentAn existing document, copied into an independent document.

bounds

Returns GPXBounds, or null when the document contains no position points.

PropertyTypeDescription
minLatitudenumberMinimum latitude.
minLongitudenumberMinimum longitude.
maxLatitudenumberMaximum latitude.
maxLongitudenumberMaximum longitude.

Route Editing Methods

MethodDescription
setStartPoint(point)Sets the route's start point.
setEndPoint(point)Sets the route's end point.
addWaypoint(point)Adds a waypoint.
appendTrackPoint(point)Appends a point to the current track.
clearTrack()Clears track points while preserving the start, end, and waypoints.

GPXPointInit

FieldTypeRequiredDescription
latitudenumberYesLatitude.
longitudenumberYesLongitude.
elevationnumberNoElevation.
timestringNoTime string; ISO 8601 is recommended.
namestringNoPoint name.

Export Methods

MethodReturnsDescription
toString()stringExports GPX XML text.
toBlob()BlobExports a blob with the MIME type application/gpx+xml.