Routemaster GPS format: .rte

.rte format is a recursive XML format for GPS tracks.

By convention the first line reads

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>

This specifies the character coding, which is the XML default anyway. I don’t suppose anything will go wrong if it is omitted.

The second line may read:

<!-- https://www.routemaster.app/rte.html -->

This is a comment which will refer any casual visitor to the present page.

The ‘document element’ – i.e. the root of the XML parse tree – is ‘<route>’. So the file will look something like this:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!-- https://www.routemaster.app/rte.html -->
<route>
  <name>Land’s End–JOG</name>
  ...
</route>

The extensibility of XML allows software to add tags and attributes not recognised by the official definition. A couple of the tags used by routemaster should be seen in this light. I shall probably cut back on them.

The attribute type is commonly used in .rte format; a tag’s attributes and elements (i.e. its subordinate tags) may vary according to its type. For instance a route may have type ‘index’, and may then have elements not expected in a route of default type.

On this page, documentation applying to ‘route[index]’ refers to routes of type ‘index’ whereas documentation of ‘route[]’ refers to routes of default type, i.e. with no type specified.

My thinking is that if someone wants to introduce a new type (eg. ‘pdf’ for the desc element), then they can do so without clashing with my own descriptions. They can do so either as a private understanding, or by proposing it as an addition to the format definition, in which case other applications can decide whether to interpret it or ignore it.

type meaning elements
– A sequence of points to be taken in order. pt, name, desc, stars, stats, info, index, gallery, srcid, optimised, imgdef, origin.
geo A list of unordered points.
tour An ordered list of tracks. route[], route[geo], route[index], name, img, stars, stats, info, index, gallery, tracklink.
index An unordered list of tracks.
metaindex An unordered list of indexes. route[index], name, img, stats, info, gallery, tracklink.
segments A sequence of tracks to be taken in order. route[], name.

If a route is of type ‘geo’, then all of its points are handled as being themselves of type ‘geo’.

<route type="index">
  <name>Long distance rides</name>
  <route>
    <name>Land’s End–JOG</name>
    <pt... />
    ...
  </route>
  <route>
    <name>C2C</name>
    <pt... />
    ...
  </route>
</route>

The most important component of a route is its points, but first we will describe the tags supplying additional information.

Name of the route (utf-8), included as a text element, as shown above.

Route description as a text element (often a cdata).

type meaning
utf-8 Plain text.
routemaster A simple markup used by routemaster containing a few HTML tags and one additional feature, namely additive links.

<route>
  <name>Land’s End–JOG</name>
  <desc type="utf-8">A ten-day ride.</desc>
  ...
</route>

A quality rating for the route, given as an integer in the range 1–5 in a text element. ‘5’ is best, ‘1’ least good. Rating absent means no rating given.

<route>
  <name>Land’s End–JOG</name>
  <stars type="1-5">3</stars>
  ...
</route>

An image associated with a route or point.

type meaning
– A URL (or pair of URLs at different resolutions) for a single image.
pix The names of one or more images defined in a pix photo list, which in turn is included under an imgdef tag.

If the default type is used, the img tag has the following attributes:

attribute meaning
width pixel width of the image.
height pixel height of the image.
scale scale factor for the resolution of the second image URL if two are given.
stars ‘*’ if the image is particularly good.

When routemaster creates a metaindex from individual indexes, it associates with each index the starred images it contains.

<route type="index">
  <name>Lago Maggiore</name>
  <gallery title="Lake Maggiore mountain biking 2023">
    https://www.masterlyinactivity.com/maggiore/pix.html
  </gallery>
  <route>
    <name>Monte Nudo</name>
    <date>Sun Sep 03 2023</date>
    <stars type="1-5">3</stars>
    <img width="196" height="140" scale="2.5">
      https://www.masterlyinactivity.com/maggiore/images/nudoview@t.jpg
      https://www.masterlyinactivity.com/maggiore/images/nudoview@0.jpg
    </img>
    <img width="140" height="196" scale="2">
      https://www.masterlyinactivity.com/maggiore/images/nudopath@t.jpg
      https://www.masterlyinactivity.com/maggiore/images/nudopath@h.jpg
    </img>
    <img width="140" height="196" scale="2.5">
      https://www.masterlyinactivity.com/maggiore/images/nudoleafs@t.jpg
      https://www.masterlyinactivity.com/maggiore/images/nudoleafs@0.jpg
    </img>
    ...
  </route>
</route>
...

<route>
  <name>Monte Carza</name>
  <stars type="1-5">5</stars>
  <imgdef type="pix">
    https://www.masterlyinactivity.com/maggiore/list.xml
  </imgdef>
  <pt lat="46.01926" lon="8.68277" h="232" t="2023-09-07T07:14:36.000Z">
    <img type="pix">stambecco</img>
  </pt>
  <pt lat="46.01956" lon="8.68353" h="232" dt="22.000"/>
  ...
  <pt lat="46.02308" lon="8.68143" h="266" dt="2.000"/>
  <pt lat="46.02302" lon="8.68098" h="271">
    <img type="pix">moggie</img>
  </pt>
  <pt lat="46.02297" lon="8.68053" h="275" t="2023-09-07T07:28:13.000Z"/>
  ...
</route>

A turn instruction associated with a point. It has two attributes, ‘label’ and ‘caption’, and may be used as an alternative to ascribing these attributes to the point directly.

<mark label="Obstacle" caption="Skills section"/>

[You have a free choice between providing a label and caption as attributes of a point or as attributes of its ‘mark’ element. I use this flexibility to keep each point on a single line subject to its length not exceeding 80 characters.]

Information enabling an application to create images from the entries supplied with <img> tags. At present it is defined only for the attribute ‘pix’, in which case it supplies the URL of a pix photo list, as illustrated in the preceding example.

The URL of a track. This is needed in indexes in order to be able to link to the individual tracks and in metaindexes in order to link to the indexes.

<route type="index">
  <name>Long distance rides</name>
  <route>
    <name>Land’s End–JOG</name>
    <tracklink>
      https:// ... /lejog.rte
    </tracklink>
    <pt... />
    ...
  </route>
  ...
</route>

The stats field contains a synopsis of a route for display in an index, or of an index for display in a metaindex. It has a rigid text format, exactly as in the examples which follow, except that different words may be used in different languages, which isn’t very helpful. (My own parsing code ignores the words and breaks out the numbers looking at the punctuation and units.)

<route type="index">
  <name>Long distance rides</name>
  <route>
    <name>Land’s End–JOG</name>
    <stats type="routemaster">
      Distance 1263.2km; ↑10397m ↓10408m; altitude 2-752m
    </stats>
    <pt... />
    ...
  </route>
  ...
</route>

<route type="metaindex">
  <name>Around Britain</name>
  <route type="index">
    <name>Scotland</name>
    <stats type="routemaster">7 routes; 257km; ↑5262m</stats>
    ...
  </route>
</route>

Further information about a route or set of routes. The text content is a URL. A title may also be provided.

<route type="index">
  <name>Long distance rides</name>
  <route>
    <name>Land’s End–JOG</name>
    <info title="My long ride">
      https:// ... /lejog.html
    </info>
    <pt... />
    ...
  </route>
  ...
</route>

A higher level index or metaindex containing the route or index itself. The user will be given a link to view this higher index in routemaster. The text content is a URL, which may be relative to the track containing it (or may of course be absolute). A title may also be provided.

<route type="index">
  <name>Long distance rides</name>
  <index title="Rides in the UK">UKrides.rte</index>
  <route>
    <name>Land’s End–JOG</name>
    <pt... />
    ...
  </route>
  ...
</route>

A photo gallery pertaining to a route or set of routes. The text content is a URL. A title may also be provided.

<route type="index">
  <name>Long distance rides</name>
  <route>
    <name>Land’s End–JOG</name>
    <gallery title="Lejog photos">
      https:// ... /lejogpix.html
    </gallery>
    <pt... />
    ...
  </route>
  ...
</route>

The date on which a route was ridden. A text string.

<route type="index">
  <name>Lago Maggiore</name>
  <route>
    <name>Monte Nudo</name>
    <date>Sun Sep 03 2023</date>
    ...
  </route>
  ...
</route>

The name of the original recording of a GPS track. A text string. This is used by routemaster to keep track of the original FIT file from which a .rte file with a meaningful name has been produced.

<srcid type="utf-8">2026-03-12-09-38-37</srcid>

A text string in a rigid format used by routemaster to avoid re-optimising an already optimised track.

<route>
  <name>Monte Carza</name>
  <optimised type="routemaster" from="10788" to="663"
             tol="15" maxsep="95" wppenalty="700" vweight="1.0"/>
  <pt lat="46.02008" lon="8.68385" h="232" dt="24.000"/>
  ...
</route>

This is a technical field used for disambiguating relative links.

A track in .rte format mat contain links (or equivalent) which may be relative or absolute. If they are relative, and the track is moved (in particular, if it is downloaded from the web), then its location changes and relative links can no longer be interpreted. The origin field contains the information needed to make sense of them. Two values are defined for its type attribute, namely ‘uri’ and ‘file’. The former is used for a track whose origin is on the web, and is a full URL:

  <origin type="uri">
    https://www.masterlyinactivity.com/routemaster/routes/wales/Crugynci.rte
  </origin>

An origin of type ‘file’ is less useful. If a track is loaded through the browser’s file import mechanism, then the importing software will be told its name but not its full directory path. The origin is therefore provided for completeness but does not allow relative links to be disambiguated.

  <origin type="file">AfonLlyfnant.rte</origin>

routemaster itself does not make use of the origin field on input: it knows where it has got the track from and stores that location. It then fills in the origin on output.

A pt is a point on a route. By default points belong in the order in which they are given; a point which does not belong to a sequence may be given geo as its type attribute. Surveyors produce points of type geo; mountain bikers produce points of default type.

The following attributes are also available:

attribute meaning observations
lat latitude (°) obligatory
lon longitude (°) obligatory
h altitude (m) optional
t time optional; a standard UTC date field
dt time difference (s) optional; the time advance from the previous point.
label label of a turn instruction. optional; drawn from a small predefined set.
caption caption of a turn instruction. optional; a short free text string. If no label is provided, ‘generic’ is assumed.

The dt field allows a more compact style than is obtained by providing a date stamp for every point. It is an error to specify a dt unless the date/time of the preceding point is determined, either as a timestamp or relative to its own predecessor.

You should not invent times for completeness. If you don’t have a time for a point, leave it out.

Only three elements are defined for points, namely mark and img as described above, and desc as described for routes. Descriptions must be supplied as included elements, not as attributes.

<route>
  <name>7 Termini</name>
  <imgdef type="pix">
    https://www.masterlyinactivity.com/maggiore/list.xml
  </imgdef>
  <pt lat="45.98191" lon="8.74084" h="129" t="2023-09-04T07:48:50.000Z"/>
  <pt lat="45.98164" lon="8.74110" h="129" dt="7.000"/>
  <pt lat="45.98123" lon="8.74123" h="129" dt="11.000"/>
  <pt lat="45.98114" lon="8.74161" h="129" dt="7.000"/>
  <pt lat="45.98086" lon="8.74168" h="127" dt="11.000"/>
  <pt lat="45.98080" lon="8.74183" h="126" dt="4.000"/>
  <pt lat="45.98095" lon="8.74226" h="127" dt="17.000" label="Right" caption="Ciclovia"/>
  <pt lat="45.98020" lon="8.74276" h="127" dt="22.000">
    <img type="pix">montegrino</img>
    <mark label="Left" caption="join road"/>
  <pt lat="45.97956" lon="8.75721" h="125" dt="5.000"/>
  ...
</route>

Notice that the time increments illustrated are all whole numbers of seconds. This is how they are recorded on a Garmin, though decimal fractions are permitted in .rte format.

Some fuller examples can be consulted on our web site.

A simple route. Notice that the ‘yaradetour’ image is attached to a geo point, i.e. to a point not lying on the track itself.
An index.
A metaindex.

It seems to me that it is useful to say how some of the values are intended to be interpreted.

A route is a collection of routes or points which belong together. In the case of points, they usually comprise a route in the normal sense.
A point is a position in space.
A route of default type is a route in the normal sense. An index is a collection of related routes. A tour is a sequence of related routes to be taken in order. A metaindex is a collection of related indexes. A route of type ‘segments’ is intended as an editor temporary: if you want to save your state in the middle of a complicated edit, you save your current version as this type. Navigation devices are not expected to display routes not of default type.
The name of the route is the label by which it is accessed on navigation devices, and will be used as a title on display devices. It should be a short string. It can be confused with the filename used to store the route; routemaster tries to keep the two in step.
The desc (description) is a piece of text as long as you want, which in principle might allow any level of formating. Devices with small screens may not wish to display them.
Stars are a quality rating. routemaster does not support a difficulty rating because I find them so inconsistent.
An img is self-explanatory. It may be worth distinguishing between thumbnails and display images. routemaster images of default type are intended for thumbnails; images of type ‘pix’ are intended for display. I consider .mp4 to be a valid extension for display images (but not for thumbnails). In general thumbnails are easy to display, but the correct display of display images needs to take account of screen size and resolution, and is best accomplished if each image exists in several sizes whose properties are recorded in a separate configuration file (which is why I have type ‘pix’). This is especially the case if the images are being accessed over the internet, in which case bandwidth limitations make it inadvisable to fetch large images and reduce their size for display. routemaster should (but doesn’t) allow images of default type to be attached to points (the icon would be generated on the fly).
A mark gives additional information about a point. It is intended to be useful for navigation, and the icon corresponding to it may be shown on a map.
A mark’s label is a short string of English text drawn from a small predefined set. It is intended to be converted into an icon or translated into the user’s language for display. No predefined set is stipulated. It is expected that the set built into routemaster (currently comprising 20 labels) will be used, but software using .rte tracks is at liberty to work with a different set. routemaster could, if desired, allow alternative sets. [In this respect .rte differs from other formats. .tcx and .fit stipulate specific predefined sets, whereas .gpx leaves the set open.]
A mark’s caption is a short string of amplifying text, intended to be displayed alongside the label (but applications are not expected to be able to translate them). Captions may be truncated if necessary.

Other values are adequately described in the text.

type	meaning	elements
–	A sequence of points to be taken in order.	pt, name, desc, stars, stats, info, index, gallery, srcid, optimised, imgdef, origin.
geo	A list of unordered points.
tour	An ordered list of tracks.	route[], route[geo], route[index], name, img, stars, stats, info, index, gallery, tracklink.
index	An unordered list of tracks.
metaindex	An unordered list of indexes.	route[index], name, img, stats, info, gallery, tracklink.
segments	A sequence of tracks to be taken in order.	route[], name.

type		meaning
utf-8		Plain text.
routemaster		A simple markup used by routemaster containing a few HTML tags and one additional feature, namely additive links.

type		meaning
–		A URL (or pair of URLs at different resolutions) for a single image.
pix		The names of one or more images defined in a pix photo list, which in turn is included under an imgdef tag.

attribute		meaning
width		pixel width of the image.
height		pixel height of the image.
scale		scale factor for the resolution of the second image URL if two are given.
stars		‘*’ if the image is particularly good.

attribute	meaning	observations
lat	latitude (°)	obligatory
lon	longitude (°)	obligatory
h	altitude (m)	optional
t	time	optional; a standard UTC date field
dt	time difference (s)	optional; the time advance from the previous point.
label	label of a turn instruction.	optional; drawn from a small predefined set.
caption	caption of a turn instruction.	optional; a short free text string. If no label is provided, ‘generic’ is assumed.