Following various discussions and requests over the previous years, I’ve adapted parsing of the machine-readable osmc:symbol tag in waymarkedtrails for route symbols to cover more use cases. The new implementation comes a bit closer to what is specified on the wiki website, most notably now supporting a second foreground, but also extending the list of supported backgrounds. This posts gives a bit of background on the changes.

Supported syntax

The official specification of the osmc:symbol tag always had the issue that it largely relies on guessing the function of its parts from their content. A part called red_bar? Must be a foreground description because there is no “bar” background and the content looks to be too long to be a text description, too. This is a viable way of describing something but not very robust against typos and it makes it very hard to extend the value set. waymarkedtrails has therefore implemented a subset of the specification that could be parsed in a way that the function is determined from the position of the parts. This subset was essentially: waycolor[:background[:foreground[:text[:textcolor]]]] Unfortunately this approach made it impossible to support the second foreground when it popped up on the wiki page and that has left users confused ever since.

User mueschel has recently re-analised the format and came to the conclusion that we can still keep the positional approach when sticking to the following combinations of part descriptions:

waycolor:background waycolor:background:foreground waycolor:background:foreground:foreground2 waycolor:background:foreground:text:textcolor waycolor:background:foreground:foreground2:text:textcolor

The one officially allowed variant that isn’t covered is waycolor:background:text:textcolor. Luckily this variant isn’t really used in practice with very minor exceptions. And it can easily be made compliant by adding an empty foreground: waycolor:background::text:textcolor.

So, going forward, the listed five variants is what waymarkedtrails officially supports.

You may have noted, that the old syntax allowed one more variant using a text with default color black: waycolor:background:foreground:text. There are about 1.5k relations tagged in this way. For sake of backward-compatibility, this will remain working for the time being. Be aware however, that this kind of syntax hasn’t been compliant with the official wiki page for years now. You can simply “fix” the sytnax by adding a text color: waycolor:background:foreground:text:black.

Second foreground

With the new syntax, a second foreground symbol is now fully supported. There are no restrictions on which symbols to combine. waymarkedtrails will blindly paint the two foregrounds above each other, whether it makes sense or not. So please use with care.

Here are some examples:

a tri-color symbol (red:blue:black_lower:white_bar)

a star (black:white:black_cross:black_x)

a tri-color circle (black:green_circle:yellow_circle:red_dot)

You can use the preview function on waymarkedtrails to try out if the value you want to add makes sense.

Note: you may have noticed that the *_red_diamond foreground symbol has disappeared from the list of supported foregrounds. This symbol has always been a bit odd in being two-colored. It will continue to work but I recommend replacing it with the two-foreground version: *:*:*_diamond:red_diamond_right.

More background shapes

As part of the changes, I have also introduced support for more background shapes(*): _stripe, _bar, _diamond and _diamond_line. This is mainly in response to US mappers, who have observed that the base shape for their core shape for markings is a stripe rather than a square, If the stripe is multicolored, then using a *_stripe foreground with a second foreground doesn’t really give the expected results.

I’m aware that this unilateral step might make life a bit harder for other data consumers. But the change is minimal and compatible with all data consumers who support optional backgrounds. Let’s see if the idea of background shapes is taken up by mappers.

(*) The original idea was to really dispose of the requirement for every symbol to be rectangular and have pretty circular and diamond-like shapes on the map. Sadly, this requires support for clipping in SVG which our rendering software Mapnik doesn’t do right now. So this part of the implementation has to wait.

Documentation

You can find the full documentation of waymarkedtrails’s handling of osmc:symbol at https://hiking.waymarkedtrails.org/osmc_symbols.html.