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.
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.
u-turn and gets a second look in decision five, because the angle alone cannot
tell a hairpin from turning round.
10 decisions, in the order the code makes them
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.
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.
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.
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.
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:
<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).
Two settings, and the four thresholds they change
| Setting | Moves | Value | What 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.