Help & documentatie

Bijlage: wat er in een GPX-bestand van PitStopper zit

Een GPX-bestand van PitStopper is geen "kale GPX". Het is een geldig GPX 1.1-bestand dat elke app kan openen, maar het bevat extra informatie waar de GPX-standaard geen plek voor heeft: de kleur en breedte van de routelijn, afslagaanwijzingen, POI-iconen en -kleuren, en geschatte tijden. Deze pagina zet de toevoegingen op een rij, welke exportoptie elk ervan regelt en precies waar in de XML het staat - handig als je je eigen tools schrijft, bestanden vergelijkt of je afvraagt waarom een andere app meer (of minder) toont dan je verwachtte.

GPX in het kort

Een GPX-bestand is XML: elementen in elkaar genest, in een volgorde die de GPX 1.1-standaard vastlegt. Dit zijn de elementen die er hier toe doen.

Omdat de standaard <sym>, <type> en <cmt> open laat, bestaat veel van wat een PitStopper-bestand nuttig maakt uit waarden waarover andere apps het eens zijn, niet uit nieuwe elementen. Al het andere gaat in <extensions>.

Welke app leest dit?

We houden geen lijst bij. Apps veranderen van versie tot versie wat ze lezen, vaak zonder het te zeggen, en een tabel daarvan zou verouderen terwijl hij er nog steeds als naslag uitziet. Deze pagina houdt het bij wat een bestand bevat en waar. Wil je zien wat er in een eigen bestand zit, open het dan in de GPX-inspector; voor wat een app leest, is de eigen documentatie van die app de plek (een paar staan gelinkt onder Van de apps zelf). Leest een app ons bestand anders dan je verwacht, laat het ons weten.

Waar elke toevoeging staat

De opties staan in Exporteren → Een bestand exporteren, met GPX geselecteerd (zie GPX exporteren). "Altijd" betekent dat het zonder optie wordt weggeschreven.

Foto's en bijlagen in een .gpz

Een waypoint, track of route noemt zijn foto met een standaard <link> waarvan de href een pad in het archief is; de afbeelding staat in de zip op dat pad. Een stop uit een .gpz die in Locus Map gemaakt is, ziet er zo uit:

<wpt lat="51.0411449" lon="3.9846805">
  <ele>6.49</ele>
  <time>2026-10-07T06:06:14.000Z</time>
  <name>Kapel</name>
  <link href="files/screenshot_20260504-175910.png"></link>   <!-- the photo, in the zip -->
  <sym>Scenic Area</sym>                                   <!-- the icon: "Scenic Area.png" in the zip root -->
</wpt>

• Lezen - het pad wordt opgezocht vanaf de wortel van het archief (eerst met exact dezelfde hoofdletters, dan ongeacht hoofdletters). Alleen bestanden die een link noemt, worden uitgepakt. Een afbeelding (gecontroleerd op de inhoud: JPEG, PNG, WebP of GIF) is een foto; elk ander bestand (PDF, document, audio, video, webpagina) wordt als bijlage bewaard met de bytes onaangeroerd, aangeboden om te downloaden en nooit weergegeven. Limieten: 10 MB per bestand, 40 MB in totaal.
• Bewaard - de originele bytes, één keer per afbeelding opgeslagen (op basis van een SHA-256 van de inhoud) in de eigen database van de browser, met de link precies zoals hij geschreven was.
• Geschreven - een .gpz-export zet elke foto en bijlage terug op zijn pad, onder files/, met dezelfde <link> (op de <trk>, na de naam, voor die van een track). Claimen twee verschillende foto's hetzelfde pad, dan krijgt de tweede er -2 bij. Een foto buiten files/ wordt erin verplaatst, zodat hij nooit een icoon tegenkomt (iconen staan in de wortel van het archief). Een gewone .gpx laat relatieve links weg; links met http, https en mailto worden altijd geschreven.
• Ook op dat waypoint - <ele> wordt de hoogte van de stop en <time> zijn eigen tijd, en beide worden teruggeschreven; de afbeelding van <sym> wordt het icoon van de stop (zie Iconen in een .gpz).

Hoe dit er in PitStopper uitziet, lees je bij Foto's en bijlagen in een .gpz.

Namespaces

Een voorbeeld met uitleg

Een ingekorte export met de meeste opties aan: één afstandsmarkering, één café met een ster, en een track met een afslag, een rotonde en een wisseling van ondergrond.

<gpx version="1.1" creator="PitStopper.net"
  xmlns="http://www.topografix.com/GPX/1/1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:gpxx="http://www.garmin.com/xmlschemas/GpxExtensions/v3"
  xmlns:gpx_style="http://www.topografix.com/GPX/gpx_style/0/2"
  xsi:schemaLocation="http://www.topografix.com/GPX/1/1 https://www.topografix.com/GPX/1/1/gpx.xsd">
  <metadata>...</metadata>

  <wpt lat="51.041" lon="3.99">                     <!-- a distance marker -->
    <time>2026-10-05T08:04:00Z</time>               <!-- estimated times -->
    <name>1 km</name><desc>1 km</desc><sym>Dot</sym><type>km_marker</type>
  </wpt>

  <wpt lat="51.0455" lon="3.9902">                  <!-- a starred cafe -->
    <time>2026-10-05T08:02:00Z</time>
    <name>Cafe Centr L20m</name>                    <!-- short name + "on your left, 20 m" -->
    <cmt>coffee. Closes early Sunday</cmt>          <!-- type + your note -->
    <desc>Full name: Cafe Centraal. Cafes. Hours: Mo-Sa 08:00-18:00</desc>
    <src>OpenStreetMap</src>
    <link href="https://www.openstreetmap.org/node/11">...</link>
    <sym>Restaurant</sym>                           <!-- Garmin symbol -->
    <type>FOOD</type>                               <!-- course-point type -->
    <extensions>
      <xsi:gpx>
        <color>#FFFF00</color>                      <!-- starred colour (else the category colour) -->
        <background>square</background>             <!-- starred shape -->
        <icon>amenity_cafe</icon>                   <!-- OsmAnd icon -->
      </xsi:gpx>
    </extensions>
  </wpt>

  <trk>
    <name>My ride</name>
    <extensions>                                    <!-- line colour and width -->
      <gpxx:TrackExtension><gpxx:DisplayColor>DarkBlue</gpxx:DisplayColor></gpxx:TrackExtension>
      <gpx_style:line><gpx_style:color>1976D2</gpx_style:color><gpx_style:width>5</gpx_style:width></gpx_style:line>
      <xsi:gpx><color>#1976D2</color><width>5</width></xsi:gpx>
    </extensions>
    <trkseg>
      <trkpt lat="51.05" lon="3.99"><ele>3</ele>
        <extensions><xsi:gpx><route_information>paved</route_information></xsi:gpx></extensions>
      </trkpt>
      <trkpt lat="51.0455" lon="3.99"><ele>4</ele>
        <cmt>High Street</cmt><sym>left</sym>       <!-- turn left onto High Street -->
      </trkpt>
      <trkpt lat="51.041" lon="3.99"><ele>5</ele>
        <sym>roundabout_e3</sym>                    <!-- roundabout, third exit -->
        <extensions><xsi:gpx><route_information>unpaved</route_information></xsi:gpx></extensions>
      </trkpt>
    </trkseg>
  </trk>
</gpx>

Van de apps zelf

Waar de apps zelf beschrijven wat ze ondersteunen. Dit zijn hun woorden, zoals ze er stonden toen we ze lazen; apps veranderen, dus controleer het in de app zelf.

• OsmAnd - OsmAnd GPX-formaat: waypoint <icon>, <background> (cirkel, vierkant, achthoek - de achthoek wordt als cirkel getekend) en <color>
• Cruiser - afslagen in de <sym> van het trackpunt en route_information (verhard, onverhard); kleuren van waypoints; namen van Garmin-iconen; .gpz-bestanden openen
• Locus Map - iconen die passen bij Garmin-symboolnamen; afslagen in de "Locus-stijl" van BRouter (BRouter-profielgids, turnInstructionMode)
• Organic Maps en CoMaps - hun GPX-lezer (Organic Maps, CoMaps) leest <color> en Garmins DisplayColor voor tracks en waypoints, met een vaste trackbreedte
• gpx.studio - de GPX-lezer verwerkt kleur en breedte uit gpx_style
• GPX Viewer - "Color from file" voor tracks; symboliconen uit een .gpz
• Garmin - het GpxExtensions v3-schema: DisplayColor op tracks en routes (voor waypoints is er geen)
• De volgorde van de kleuren - het verslag van een gebruiker van Locus en Cruiser over eerst Garmin schrijven, dan gpx_style, dan xsi:gpx

PitStoppers eigen elementen

Voor een paar dingen die PitStopper bewaart, bestaat in geen enkele GPX-extensie een element. Daarvoor voegen we onze eigen elementen toe, in het blok <xsi:gpx> dat Cruiser, OsmAnd en Locus Map al lezen. De regel is eenvoudig: een app die een element niet kent, slaat het over, dus ze maken nooit een bestand kapot. We houden ze weinig, eenvoudig en hier beschreven, zodat elke app ze ook kan lezen.

<trk>
  <name>Morning ride</name>
  <extensions>
    <xsi:gpx>
      <physicalWidth>40</physicalWidth>        <!-- the band, under: 40 m, 20 m either side -->
      <physicalColor>#401976D2</physicalColor> <!-- the line colour, 25% -->
      <color>#1976D2</color>                  <!-- the line, on top -->
      <width>4</width>
    </xsi:gpx>
  </extensions>
  <trkseg>...</trkseg>
</trk>

Ze staan vóór <color> en <width>, in tekenvolgorde: de band onder, de lijn erbovenop. Een KML-export houdt dezelfde volgorde aan en schrijft de placemark van de band vóór die van de route. De corridorelementen zijn voorgesteld door een van onze gebruikers (oktober 2026), zodat een band geen tweede track nodig heeft. De GPX-inspector noemt beide elementen, controleert of <physicalColor> een geldige kleur is, en toont de corridor in de samenvatting en bij "In en uit".

Goed om te weten

• Kleuren gaan erin en eruit. Als je een GPX-bestand laadt, houdt een track de kleur, breedte en transparantie die hij had, gelezen eerst uit gpx_style, dan uit xsi:gpx, dan uit de kleurnaam van Garmin; een lijnstijl uit KML wordt ook gelezen. Bij export wordt dezelfde stijl in alle drie de vormen geschreven, zodat een route die in de ene app gekleurd is, in de andere gekleurd aankomt. Garmin kan alleen de dichtstbijzijnde van zijn 16 kleuren aan, zonder breedte. De eigen lijninstellingen van Locus Map in gpx_style:line (zoals een lijnpatroon) blijven bewaard en worden teruggeschreven, met de kopie van kleur en breedte voor Locus gelijkgetrokken met de jouwe.
• Transparantie stel je per route in bij Route-instellingen of in het routebeheer: dekkend, 25%, 50% of 75% transparant, of volledig transparant. Volledig transparant betekent "verborgen in andere apps" - het wordt geëxporteerd als Garmins Transparent en een dekking van 0 - terwijl PitStopper de route nog steeds tekent, gestippeld, zodat je hem ziet.
• Breedte stel je in bij Route-instellingen met een schuifregelaar, van 1 tot 24 px, en een voorbeeld erboven toont de lijn met kleur, transparantie en streepjes voordat je opslaat. Het routebeheer heeft vier snelle breedtes. De breedte gaat in alle drie de vormen mee.
• Een corridor (Route-instellingen) tekent een doorzichtige band in de kleur van de route, zoveel meter aan weerszijden ervan, die zijn breedte op de grond houdt als je zoomt. Hij gaat mee in elk formaat dat hem kan bevatten, en komt ook weer binnen: in GPX en .gpz als <physicalWidth> op de track (zie PitStoppers eigen elementen); in KML en .kmz als tweede lijn onder de route met gx:physicalWidth, de vorm die Google Earth en Locus Map tekenen. Opent PitStopper een KML, dan wordt die tweede lijn weer de corridor van de route, geen eigen route. FIT heeft er geen vorm voor.
• De trackkleur wordt op drie manieren geschreven omdat elke familie van apps een andere leest: eerst Garmins gpxx, dan gpx_style, dan xsi:gpx - de volgorde die volgens een gebruiker van Locus en Cruiser sommige lezers nodig hebben (zie de bronnen hierboven).
• Hoe een stuk gerouteerd is gaat mee in de <src> van het trackpunt: beeline voor een rechte lijn, osm voor willekeurige paden. Die twee betekenen in elke routeplanner hetzelfde, dus het is de moeite waard ze te bewaren: Cruiser laat een stuk met beeline recht als hij de route opnieuw berekent (hij heeft geen profiel voor willekeurige paden, dus negeert osm). Locus Map leest nog geen van beide; de ontwikkelaar is het gevraagd. Cruiser schrijft er ook de naam van zijn profiel in (fastest, curvy enzovoort); PitStopper bewaart die zoals ze zijn, maar andere routeplanners tekenen daarmee niet dezelfde weg. (Van een gebruiker van Locus en Cruiser, november 2026.)
• Meerdere routes in één bestand ("Gecombineerd", de standaard) geven één <trk> per route, elk in zijn eigen kleur. "Aparte bestanden" geeft een zip met GPX-bestanden van één route elk.
• Iconen gaan erin en eruit. Een .gpz uit een andere app brengt de PNG mee voor elke <sym> die de stops gebruiken (afbeeldingen die geen stop gebruikt, blijven weg); PitStopper biedt aan de stops ermee te tekenen, en schrijft dezelfde symboolnaam en de originele afbeelding terug als een stop met zo'n icoon wordt geëxporteerd in een .gpz met iconen. Het eigen ankerpunt van het bestand (hscc in het referentiebestand van Cruiser) blijft bewaard als de stops het erover eens zijn, en de <scale> van elke stop tekent het icoon zoveel groter of kleiner.
• Locus Map en .gpz-iconen (uit de tests van een gebruiker met de bèta van Locus Map, oktober 2026): het leest naast PNG ook SVG-iconen uit een .gpz, en als beide er zijn gebruikt het de SVG. Het tekent elk .gpz-icoon met het midden van de onderkant op de plek (hsbc), welk ankerpunt het bestand ook vraagt, en gebruikt het <anchor> of de kleur van een waypoint nog niet. Daardoor staan onze eigen iconen, die gecentreerd getekend zijn, in Locus net boven de plek; je eigen iconen staan standaard op midden onder, wat Locus toch al doet.
• Een stop die je geïmporteerd hebt houdt zijn eigen <extensions> uit het oorspronkelijke bestand, in plaats van het icoon, de kleur en de vorm die PitStopper zou toevoegen. Uit het bestand van een andere app houdt hij ook zijn eigen <desc>, <cmt> en <link>.
• Alleen POI's exporteren schrijft geen kleuren, maar voegt wel het OsmAnd-icoon en de vorm van de markering toe.
• Tijden worden nooit verzonnen: geschatte tijden hebben een starttijd nodig, en een track die met opgenomen tijden binnenkwam, houdt die, wat de optie ook zegt.
• FIT en KML dragen dezelfde informatie op hun eigen manier: FIT als coursepunten, KML als stijlen en mappen. Zie FIT exporteren en KML exporteren.