How a bend becomes a turn-by-turn instruction

When PitStopper writes turn-by-turn (TBT) instructions into a GPX track, for Match to Roads or a planned route, eleven steps decide which bends get a cue and what each cue says. Navigation apps such as Cruiser and Locus Map read those cues and announce them as you ride. We set each threshold after looking at a real file where the old value went wrong. They all live in src/route/match/thresholds.js.

This page reads its numbers from that file and draws its arrows with the app's own icons, and the u-turn answers below come from the matcher's own code. No routing is involved: the turns come from the shape of the line alone.

Decision one

The angle picks the band

The angle is the change in bearing over a fixed length of line on each side of the point. Measuring between neighbouring vertices does not work: at a kerb they can be centimetres apart.

The u-turn band is only a first guess. Anything in it leaves this dial as u-turn and gets a second look in decision five, because the angle alone cannot tell a hairpin from turning round.

The whole run

10 decisions, in the order the code makes them

Decision five, in full

A u-turn, or just a very sharp bend?

A u-turn comes back along the same line. Turning back onto a road that runs alongside is a u-turn to one side, and one instruction is clearer than two lefts in a row. Anything else is a sharp turn, and calling it a u-turn would mislead. The angle alone cannot tell them apart: in one file, two turns 13° apart are a sharp left and a u-turn, because one comes back 31 m away and the other 16 m.

    We use the median gap

    The way in and the way out always meet at the turn itself, so the smallest gap is about zero for every turn. We measure the median gap along the probe distance instead.

    Where the OSM way ends

    OpenStreetMap splits its ways at junctions, so a real u-turn crosses from one way to another and a mountain switchback stays on one. Road names cannot tell us this: both legs of one u-turn we were sent are called Sportlaan.

    The rules, running

    Try a bend and see what comes out

    This runs the matcher's own code, in the same order. uTurnBranch says which test matched, and isBendOnSameRoad and isBendOffNetwork decide whether the cue is kept, so the answer here is the answer the app gives.

    negative left, positive right

      In the GPX file

      What a turn-by-turn cue looks like

      Each cue goes on the trackpoint where the turn happens, as the GPX 1.1 <sym> element, with the name of the road you turn onto in <cmt>. Via points get <type>via</type> and a name, and the start and finish are typed as vias too. This is the layout Cruiser writes, and Locus Map reads it the same way. Apps that do not know these cues just see an ordinary GPX track. Here is a cycle path crossing a street of the same name, with a left and a right 18 m apart:

      Turn-by-turn is not part of the GPX standard. GPX 1.1 gives every point a <sym> and a <type>, but leaves what goes in them up to the app writing the file. Turn names such as left and right_sharp in <sym>, and via or shaping in <type>, are a convention from Locus Map's navigation tracks, which Cruiser writes too and PitStopper follows. Garmin and OsmAnd keep their turn instructions in formats of their own, so they will not announce these.
      <trkseg>
        <trkpt lat="51.041071" lon="3.966321">
          <ele>3.2</ele>
          <sym>pass_place</sym>
          <type>via</type>                    <!-- the start -->
        </trkpt>
        <trkpt lat="51.041338" lon="3.967057">
          <ele>3.2</ele>                      <!-- no cue: just a point on the line -->
        </trkpt>
        <trkpt lat="51.04168" lon="3.968778">
          <ele>4.0</ele>
          <cmt>Paepenbogtstraatje</cmt>       <!-- the road you turn onto -->
          <sym>left</sym>                     <!-- "turn left" -->
        </trkpt>
        <trkpt lat="51.041842" lon="3.968712">
          <ele>4.0</ele>
          <cmt>Paepenbogtstraatje</cmt>
          <sym>right</sym>                    <!-- "turn right", 18 m later -->
        </trkpt>
        <trkpt lat="51.042239" lon="3.970402">
          <ele>3.0</ele>
          <name>Finish</name>
          <sym>dest</sym>                     <!-- arrival -->
          <type>via</type>
        </trkpt>
      </trkseg>

      These are all the symbols a cue can carry, drawn with the icons PitStopper shows on the map and in the turn list. The bands at the top of this page decide which one a bend gets. The turn icon set has them at full size, with their licence. The GPX file reference lists every element PitStopper reads and writes, and you can add, change or remove a cue yourself on the map (how).

      What the rider can move

      Two settings, and the four thresholds they change

      SettingMovesValueWhat changes

      An open question. The check looks at the angle, and ignores the symbol. So a 160° switchback that decision five turned into right_sharp is still announced with hairpin warnings off, because its angle is past uTurnDeg. That can be argued for, but it is not what "hairpin warnings off" suggests, and we have not settled it yet.