Imagico.de

I have a significant backlog now of changes i made on the alternative-colors style that i have not discussed here yet. This blog post is about the largest and most significant of these changes, related to the way point symbols and labels are rendered.

Point symbol and label rendering in OSM-Carto has been in a non-satisfying state for a long time. This is largely because almost no fundamental work has been done on this part of the style for many years while the complexity in the form of the variety of different label and symbol types has grown continuously over time. Or in other words: There has been continuous pressure to add new features in the form of labels and symbols to the style combined with the almost complete absence of interest to actually rework the system of label and symbol rendering in a way that actually scales and is able to handle this complexity.

The core of the problem discussed by this blog post is the depiction of blocking elements in an automatically rendered map style. Blocking elements means graphical elements that – as a matter of principle – are not supposed to be overlapping with each other. This is the case for all labels in any map as well as typically also most pictorial symbols used.

Different methods exist to implement the requirement for elements to not overlap. The most significant one is optimizing the placement of symbols and labels accordingly. This whole field consisting of many different techniques i will not cover in this post.

Most digital rule based map rendering systems, however, are fairly primitive when it comes to handling of blocking elements. In those cases the only way of enforcing the non-overlap is by not rendering elements that would overlap other elements which have already been rendered. There is typically no support for cutting out/masking or otherwise modifying symbols to avoid overlaps with others (something i demonstrated with tree symbols in a previous post) and options to tie the rendering of graphical elements to one another are typically very limited. One of the oldest open issues of OSM-Carto on the issue tracker is dealing with exactly that limitation. I am also going to discuss this here although i will not present a solution because that is not possible without support from the rendering software.

The OSM-Carto point symbol and label system

The approach to point symbol and label placement used by OSM-Carto in light of these limitations is by separating symbols and labels into two completely independent layers. These two layers use the same SQL code meanwhile (which makes maintenance a bit easier with this kind of long queries).

This means essentially the style places all point symbols meant to be shown at a specific zoom level as far as this is possible without overlaps and then it places all labels that still fit in between the symbols. That means point symbols universally have priority over labels. And if there is only space for the symbol and not the corresponding label then only the symbol is rendered.

Conflicting symbols and labels in OSM-Carto

But because the symbols and labels are rendered completely independently this also means that labels will be placed even for features where no symbol has been rendered before. It would be possible to connect the two and render the combination of symbol and label only if there is space for both (via shield symbolizer) but only with both having the same priority. It is not possible with the tools used by OSM-Carto to render the labels with lower priority than the symbols and still tie the display of the labels to the corresponding symbol being also displayed. This leads to the awkwardness of offset labels (which are meant to show up below or above the corresponding symbol) being displayed without the corresponding symbol, leading to confusion because it looks like either the label is for a different feature or the label being at the wrong location (because of the offset).

There are several other big issues with the point symbol and label rendering system in OSM-Carto. One is that the actual style rules for rendering the symbols and labels are an unstructured >3000 lines of CartoCSS code that is essentially unmaintainable. Rules have just been added to that over time with no particular order and there is plenty of dead code in there leading to confusion. This mess is a major source of styling errors like symbols or labels having the wrong color or appearing at the wrong zoom levels.

The other big problem is that the drawing order within the two layers (which defines which symbols have priority over which other symbols and likewise for labels) is arbitrary at the moment. Developers have usually added new feature types without making a conscious choice about the priorities. At the same time not all point features are in the two main POI layers described above. Because it is considered desirable for the labels of major POIs like shops and restaurants to have priority over minor POI symbols like benches or wastebaskets there is a separate pair of low priority POI layers.

As a result of this it is not uncommon for point symbols and corresponding labels to turn up and vanish again as you zoom into the map in a highly non-intuitive way.

Under the described constraint of not being able to tie the label rendering for a feature to the successful placement of the corresponding symbol without rendering it with the same priority, there are mainly two sensible strategies to pursue – none of which is ideal in any way:

1. to keep rendering the symbols and labels separately. This leads to the known problem of having offset labels without symbols in the map. Also, since the labels will universally have lower priority than the symbols – independent of the starting zoom levels, there will still be cases where labels vanish as you zoom in, because new symbols start turning up with priorities higher than the labels.
2. to tie the label to the symbol and render them with the same priority with the disadvantage that in particular lengthy labels for high priority symbols will block lower priority symbols leading to, overall, a lower number of POIs being displayed. This has the advantage of universally avoiding the ‘offset label without corresponding symbol’ phenomenon. It also avoids the vanishing symbols problem, at least as long as symbols and labels start at the same zoom level.

As explained both approaches have their disadvantages. What we would really like instead is rendering the symbols as in the first approach but then render the labels only for those features for which a symbol has been successfully rendered. This, however, is not possible with the current tools.

Prioritizing by starting zoom level

Independent of which of the two strategies in symbol and label rendering we ultimately want to choose – the key to minimize the effect of symbols and labels vanishing as you zoom in is to prioritize them by starting zoom level. This in principle is possible to do in the OSM-Carto setup – but it would be a substantial amount of tedious work to adjust the priorities accordingly. And every time the starting zoom level of some symbol type is changed you have to re-arrange the whole thing. So this is definitely not sustainable.

This need to consistently prioritize rendering by starting zoom level was the main reason for me to look into re-designing the whole symbol and label rendering in the AC-Style. The basic idea is to specify the design parameters (like symbol shape and color, label design) and the starting zoom levels of all the different feature types and variants rendered and then have a script automatically generate the MSS and SQL code necessary to render these with the desired prioritization.

If you look at the auto-generated MSS code you will notice the absence of zoom level selectors (with the exception of those cases where design changes with zoom level). That is because for prioritization the starting zoom level needs to be available on the SQL level anyway so it is prudent to also filter by zoom level in the SQL query already. In other words: In contrast to classic OSM-Carto the SQL query of the symbols and labels layer only returns those features that are actually rendered and the MSS code only selects how to render them.

Label formatting

In addition to the difficulties of rendering labels and symbols together as discussed above there is another annoying thing with label rendering in a CartoCSS based system. Carto does not provide the means to format different parts of a label with different stylings despite Mapnik having provided support for this for quite some time. This means that if you want to separately format different parts of a label differently you have to use separate labels, resulting in the same problems as with symbols and labels – that you have no control over which of them actually get rendered in the presence of other competing blocking elements.

Carto had at some time in the past a hack that allowed integrating Mapnik XML code into a CartoCSS label string and this way supporting differentiated label formatting. But that feature was removed at some point. I re-added it and use this in the AC-Style – which, however, requires using a custom Carto version.

Notes on the implementation

Since i am not a software developer and i have neither the ability nor the ambition to develop a generic framework for symbols and labels rendering the implementation of what i described above in the AC-Style is fairly awkward and non-ideal. This applies both to the python code generating MSS and SQL and to the form in which you specify the symbol and label design that is interpreted by the script.

I emphasize this because elsewhere i have on several occasions pointed out the importance of tools in map rendering being developed for the needs of the map designer rather than for the convenience of the software developer. And this mock-up point symbol and label rendering definitely does not meet this requirement. It is merely a demonstrator showing the concept in a relative simple form. While this will be self evident to most readers i feel it is prudent to point out that software developers should not take this as a blueprint for their work.

The important thing to note is that the script implements both of the strategies i described above – you can choose which of them to generate the code for. To avoid this blog post getting too long i will not discuss the details of how this works here.

Modularization of the style

What i want to mention though is that for being able to use script generated SQL code for the symbol and label layer i modularized the project.mml file. There is now a layers subdirectory containing the individual layers (or blocks of several layers) and there is another script that assembles these into a single project.mml file based on a layers.yaml configuation file.

Apart from technically facilitating the use of auto-generated layer definitions there are mainly two reasons for this:

First – with the increasing size of SQL queries in the AC-Style (in particular the roads layer of course) project.mml became fairly hard to maintain and i was also thinking about how to facilitate easier debugging of the roads layer – which would probably involve auto-generating this as well.

Second – i am thinking about modularization of the style to allow users to choose which of the more sophisticated (and often slower) features they want to use and which not. The layers.yaml file allows specifying tags for the different layers and these should in the future allow generating custom variants of the style with specific features being selectively enabled or disabled. This so far is just the basic setup allowing this in principle. I have not actually done any work making this practically useful yet.

Practical results

Here a few examples of POI rendering with the new system. First in the symbol and label separate version (similar to OSM-Carto, but with consistent priorities):

AC-Style with separately rendered symbols and labels

and in the combined version:

AC-Style with combined symbol and label placement

Note in this second variant, if the combined shield symbolizer (symbol+label) is not successfully placed, the symbol only variant is tried. And if that fails a centered label is tried as well (second from the right). This looks a bit like the third form the right in the separately rendered version with the offset label and the symbol of two different features being shown together in a misleading fashion. Note, however, here the symbol and label are both centered on the respective POI locations, hence this is much less misleading.

You can also see the differentiated formatting of the label with the elevation values in italics. The CartoCSS code for that (requiring – as indicated – a patched version of Carto) is

shield-name: '[name]<Format face-name="Noto Sans Italic" size="9">[int_elevation]</Format>';

Another example which i derived from real world data i mentioned as a good example of how the inconsistent prioritization leads to confusing results in OSM-Carto. The data around there has meanwhile changed so the map on osm.org does not show this any more – and i made some adjustments to serve better as a demonstration.

First how it looks like in OSM-Carto. This is a sequence of samples as you zoom in from z15 to z19. The peak on the right gives you a sense of the change in scale.

At z16 you can see the hut symbol vanishes because it is blocked by a picnic site symbol – which starts being shown at z16 with higher priority than the wilderness hut, which was already visible at z15. The hut label remains because it is rendered independent of the symbol. At z17 both the picnic site symbol and the hut label get blocked by the newly appearing fire pit symbol, which continues to block the hut label (but not the symbol) at z18 – while the tower symbol appears. At z19 hut, picnic site and fire pit are all visible – plus some other minor symbols – while the tower symbol vanishes, being blocked by the newly appearing map symbol. And the tower label appears newly at z19 while the corresponding symbol vanishes – adding further to the confusion.

I admit this is a bit engineered for demonstration – though not that much – the original mapping in 2022 already contained many of the flaws this demonstrated. So these are not extremely rare corner cases, these are things happening in the map all the time.

Lets see how the new setup in the AC-Style deals with this. First the variant with separate symbols and labels:

And second – for comparison – the variant with symbols and labels rendered together.

As you can see there are no vanishing symbols in either variant any more as you zoom in. And labels vanish in the first version only. But tying the labels to the symbols of course leads to less symbols being shown because they are blocked by labels. This is only a small factor in this specific test example, practically the effect is often quite significant.

Summary

What i showed here is – as already indicated in the beginning – not a solution to the core problem of combined point symbol and label placement in maps. That would require support from the underlying rendering framework. It does, however, demonstrate how consistently prioritizing labels and symbols by starting zoom level can lead to a much improved map viewing experience with less inconsistencies and how such consistent prioritization can be ensured automatically in a Carto+Mapnik based map style.

As i have explained in the previous blog post i wanted – in light of the situation of name tagging in OpenStreetMap having been stuck for many years now – to try presenting a proof of concept how a solution to this could look like that both demonstrates the practical benefits and that shows a transit path from the status quo towards more elegant mapping concepts while maintaining the paradigm of map design to support, but not actively steer.

The difficulty with doing that is that – as i have discussed many times already now – the tools available for rule based map design have largely been stuck for even longer than name tagging in OSM. Commercial map producers have for the last ten years essentially a hundred percent focused on creating maps for the language needs and preferences of their target customers – which is a completely different problem than to create a map which shows the locally used names everywhere on the planet.

Beyond that, the whole domain of label and symbol rendering in OSM-Carto is also in a precariously unmaintained state for many years now. So when i decided to work on this i needed to do quite a lot of yak shaving first as prerequisite of implementing the name rendering in a way that is not too awkward (and in particular: To avoid the need to make tons of changes in the essentially non-maintainable and fairly chaotic amenity-points.mss file). Many of the changes made (in particular the modularization of the layer definition and the re-design of the POI symbol and label rendering with auto-generated SQL and MSS code) deserve a discussion on their own. In summary, all of these changes are highly experimental, even more so than most previous changes in the Alternative Colors style. Much of the design is code wise not very elegant. As said: this is meant to be a proof of concept, not a ready-to-use product.

As i have explained in the previous blog post, the situation with mapping of local names in OSM is severely stuck. So the usual approach of OSM-Carto to very directly depict what mappers map is not going to work because the only thing to do then would be to universally stop rendering labels based on the name tag – which is evidently not a very constructive approach. There is the possibility though to keep rendering the main use case of single names in the name tag but to selectively stop rendering the more problematic variants. This is the approach i have taken here.

One development that helped a lot with doing this is a tagging idea that was suggested a few years back as a solution for problems of rendering a map for a specific language audience (the labeling strategy of commercial maps, labeling for a specific target map viewer rather than displaying the local name everywhere) that has gained some traction meanwhile – the default_language tag. Originally meant to record the language that is the most likely language in the area (hence maintaining the illusion of there being a single local name for everything) it was recently modified by mappers in a way that is fairly close to what i suggested back in 2017. I will get to how i use this information in the following.

Interpreting multilingual compound names

Let’s first start with explaining the new name rendering logic in the hypothetical case of an English-German multilingual region:

First of all plain single names in the name tag remain being rendered as is. The primary difference (shown in the second line) is that compound names in the name tag alone (without any other name tags containing the individual names) are not shown any more. Compound names are here defined as names that:

• contain one of ‘ / ', ' - ' or ';' (slash/dash with spaces around or semicolon)
• contain words (separated by spaces) composed of characters from different scripts

And as you can see below you can have literal semicolons in names by escaping them with double semicolons:

Remember that we are in a hypothetical English-German multilingual region – but since we have no way to know that so far, it is clear that name:en and name:de are not affecting the name rendering, a single name in the name tag has priority.

If, however, components of the compound name tag are separately tagged in name:en or name:de (or any other name:<lang> for that matter) – things change:

As you can see, i only render those parts of a compound name that can also be found in the individual name tags.

What you can also see is that the separator used in rendering is a line break. This is for horizontal point labels, for line labels (like on roads, not shown so far) i use ' - '.

Single language compound names

But what about compound names with components from the same language? Here the logic is very similar, just that the individual names tags interpreted are official_name, loc_name, alt_name and name:right/name:left. name:right/name:left are even shown when there is no name tag.

This rendering logic is not directly supported by established mapping practice, it is an extrapolation of the consensus we have on multilingual names. Because there is – based on established mapping practice – no reliable way to distinguish between compound labels of a single language and multilingual compound labels, the logic has to be the same in both cases. This could change in the future through interpretation of default_language – which i am going to discuss in the following.

Using default_language

So far what i have shown is simply how map rendering can enforce the established convention that the components of a compound name tag should be also separately recorded in individual tags. This neither solves the han unification problem nor does it provide a path towards a substantially more sustainable mapping practice for name mapping. This is done by interpreting the default_language tag.

default_language was originally suggested as a tag to record the most likely language of the name tag within an administrative unit. It is, however, predominantly and increasingly used for tagging the primary or most common language or languages of an administrative unit. I use it in both meanings. There does not appear to be a clear consensus on the delimiter in that tag in case of multiple languages yet, i allow the same delimiters as for the name tag.

As the tag is applied to administrative units and not to individual features, you need to preprocess the administrative boundary data to use that efficiently in map rendering. I have a proof-of-concept process for that as well but have not published it so far because it is very preliminary – you can, however, download the results.

In addition to the default_language tags of the administrative divisions as mapped, de-duplicated in overlaps with priority on the higher admin_level, i also modify the language information in Chinese speaking areas to provide information about simplified vs. traditional Chinese (more on that later):

UPDATE boundaries SET default_language = 'zh-Hans,zh' WHERE default_language = 'zh';
UPDATE boundaries SET default_language = 'zh-Hant,zh' WHERE country = 'tw';
UPDATE boundaries SET default_language = 'zh-Hant,zh' WHERE country = 'hk' AND admin_level = 3;
UPDATE boundaries SET default_language = 'zh-Hant,zh' WHERE country = 'mo' AND admin_level = 3;


Here is how this default_language attribute is interpreted in case of our hypothetical English-German multilingual region:

As you can see the default_language value is, in this case, used for two purposes:

• to decide on the order of names in rendering.
• to render name:<lang> for lang in default_language in cases if there is no name tag.

How to write things is as important as what to write

In addition – and this might actually be the more significant part of the change because it affects a large number of people not only in multilingual regions – i use the default_language information to select different fonts in different parts of the world to address the Han unification problem.

A big disclaimer here: I am no expert in typography of any of the scripts where i vary the font based on language. If the style of script actually represents local practice in these regions and if the change as implemented here leads to better usability of the map is not really clear to me. This is not ultimately what this is about though. What i try to show is the principal feasibility of adjusting the fonts based on language.

Here is how it looks like for Chinese, Japanese and Korean (CJK). The sample towns chosen (Chuanchang and Mifune) might not be the best to demonstrate this – but they show the principle. Because the difference might be difficult to properly see at this size you can click on the sample to get a double resolution version.

Especially the following things can be observed here:

• The default rendering is Simplified Chinese. This differs from OSM-Carto, which defaults to Japanese. However, based on number of people affected, Simplified Chinese is clearly the more logical choice. Note the default is only relevant for parts of the world where default_language does not change the script style (i.e. countries outside the CJK regions).
• For single names in the name tag like here the default_language overrides the individual name tag matching to determine the language. Otherwise Chuanchang would not be rendered in the Japanese variant with default_language=ja because there is no name:ja.
• The tagging of name:zh, name:zh-Hans and name:zh-Hant is redundant in this case because all variants are identical.

Some real world tagging examples from outside the CJK domain:

Note in particular the reason why it is Brussel – Bruxelles without default_language is because the order in rendering is alphabetical w.r.t. language code based on matching with the individual names, and Brussel matches name:af here, which comes before name:fr. default_language helps resolving such ambiguities.

Some comments on the implementation:

Because i implemented this change in name rendering in combination with various other changes of significant impact on the style overall, it is a bit difficult probably to understand by looking at the code changes. The main part of the functionality is implemented in a number of SQL functions you can find in sql/names.sql. In the queries of the style layers this is used like:

  (SELECT
      way,
      name_label[1] AS name,
      name_label[3] AS font,
      ...
    FROM
      (SELECT
          way,
          carto_label_name(way, name, tags, E'\n') AS name_label,
          ...
        FROM planet_osm_polygon
        WHERE ...) AS _
    WHERE name_label[1] IS NOT NULL
  ) AS layer_name

And on the CartoCSS level you then use something like:

#layer {
  [zoom >= 14] {
    text-name: "[name]";
    text-face-name: @book-fonts;
    [font = 'jp'] { text-face-name: @book-fonts-jp; }
    [font = 'tc'] { text-face-name: @book-fonts-tc; }
    [font = 'kr'] { text-face-name: @book-fonts-kr; }
    [font = 'ur'] { text-face-name: @book-fonts-ur; }
    [font = 'bg'] { text-face-name: @book-fonts-bg; }
    ...
  }
}

Because of Mapnik’s particularities in interpreting fonts (newer versions of Mapnik seem to try to be over-clever and guess the language of a string and then select font locl accordingly) the only way to actually control the script type is to use font files which only contain a single set of glyphs and not allow choosing one of several with the locl mechanism. For Noto Sans CJK these single language fonts are readily available from Google, for Bulgarian Cyrillic i had to modify the fonts used (Acari Sans) and remove the Russian Cyrillic variant. See get-fonts.sh for details.

Some potential questions:

That was just a very quick look over this change in name rendering, skipping a lot of details. There are a number of issues i anticipate readers to see that i will try to discuss briefly here:

The name interpretation logic is complicated, doesn’t that clash with the goal to be intuitively understandable for mappers?

Yes, that is a valid point. Keep in mind, however, that a very simplistic interpretation of name tagging is what got us into the current situation in the first place. The world of geographic names is complicated and this can only be properly dealt with if mappers and data users alike embrace the complexity.

Doesn’t this actively steer mappers into changing their mapping practice?

IMO much less than the current practice of plainly rendering the name tag no matter what. The overall idea of this change is to pick up on the few things where there mappers seem to have a clear consensus and to do the necessary extrapolations/extensions of that to create a viable and consistent rendering logic that supports mappers in a consistent mapping practice based on their own consensus decisions. And the rendering logic is deliberately designed to allow adapting to future changes in mapping practice. If default_language, for example, is in the future more widely adopted, it can be considered to allow it overriding the name tag (like for example if a language in default_language is tagged individually as name:<lang> but not as part of name, or to prefer name:<default_language> over a single name in the name tag). Some decisions that might be considered steering (like allowing default_language on the feature level) are currently in the code mainly to facilitate easier testing.

Wouldn’t this require all data users to use a similarly complex logic.

No, the good things about this approach is that data users satisfied with the status quo can continue to interpret the name tag as a label tag. The quality of the name tag might over time further degrade, but this is likely to happen anyway. And if mappers embrace the possibilities this approach offers for more cleanly structured name tagging (in whatever specific form they decide to do so), it will likely become much easier to semantically interpret the name data than it is right now.

Isn’t the logic of splitting compound name tags awfully complicated? Wouldn’t it be much easier to just standardize on semicolon as separator?

I don’t think there is a huge difference between supporting one or supporting three separators. The detection of different scripts to separate compound names without separator (as it is common in particular in Africa) is a different matter. But i am pretty sure once there is a viable way to get multilingual name display without an undesired delimiter, the local communities would not be opposed to changing that. For the moment this complexity is there to support all the common multilingual name tagging variants with equal determination.

Isn’t the preprocessed default_language data highly prone to vandalism because a single tag change can massively affect large parts of the map?

If you process the data in a simplistic way (like a process newly run on a daily basis) then yes. But for data not subject to rapid changes (languages of regions do not change from one day to the other) this is a solved problem. You have to apply some change dampening, i.e. roll out a change in tagging in the processed data only once it has proven to be stable over a longer period (like a week or a month). This is not rocket science, just a bit of hand work.

Shouldn’t other tags (like brand, operator, addresses) be subject to the same font selection logic as names?

Yes. As said, this is a proof-of-concept demonstration, not a ready-to-use product.

Nice, but where is the point? If this is not included in OSM-Carto it is extremely unlikely that it will have a substantial positive influence on mapping practice.

True. But you have to start somewhere. As said, nothing of substance has changed for the past five years. This is an attempt to provide a perspective how things can change. It is up to others to decide if they support the idea.

Real world examples:

How does this look like with real data? Here you go:

Meran, Italy at z17

Kavarna, Bulgaria at z16

Brussels, Belgium at z18

Agadir, Morocco at z15

Peshawar, Pakistan at z16

In most cases some compound labels are missing because the individual names are not in other name tags or because they are written differently in those. And you can see that in some cases the order of compound labels is different because of the logic described above.

In the previous blog post i introduced a bit the idea of systematic testing in map design and how my work on that has led – as a byproduct if you want to say so – to the rendering illustrations you can find on TagDoc.

But there is another problem most automated rule based map rendering projects are faced with that can be solved with systematic testing. Map styles, in particular more complex ones like OSM Carto, face the problem that it is very hard to determine what the style actually renders (meaning which attribute combinations are rendered in a distinct fashion at what zoom levels) by looking at or by analyzing the code. The only reliable way to do that is by actually rendering things. The only meaningful index or map key of OSM Carto that exists so far is a hand curated wiki page produced by people based on their knowledge of the style.

The way systematic testing can be used to help with that is by feeding the style with various combinations of data and checking which of them results in a distinct rendering. As you can probably imagine this would require a prohibitive number of tests if you’d do that in a dump fashion. But by using heuristics to narrow this down, the effort required can be reduced to manageable level – even if you still end up with more than 100k tests in case of a map style like OSM Carto.

And this is what i want to introduce here – StyleInfo is a new tool that i created that allows you to view how various map styles depict OpenStreetMap data – based on an analysis of the style that uses heuristic systematic testing to determine what the style renders and in what form without requiring substantial up-front information about the style.

StyleInfo is structured a bit like Taginfo, it allows you to look at the different keys and tags of the OSM tagging system – but instead of showing how these tags are used in the database it shows how these tags are depicted by the selected style.

In addition you can also look at how the style depicts tags only on a specific zoom level.

All of this is cross referenced with links so you can move between the different views quite easily. A few examples:

• Tags shop=* and how they are rendered in OSM Carto.
• Rendering variants of highway=motorway as primary tag in OSM Carto v1.
• Rendering variants of highway=steps as primary tag on linear ways at zoom level 20 in OpenStreetMap FR Carto.
• Rendering variants of natural=spring as primary tag in OSM-Carto-alternative-colors.

The information about the map style this gives you is somewhat limited particularly in two ways:

• For principal reasons the results cannot be guaranteed to be complete. I have already identified a few tag combinations that are missing in some styles in the analysis and will need to make adjustments to the heuristics because of that. None the less this is still the most comprehensive documentation of OSM Carto and derivative map styles available so far.
• StyleInfo so far shows renderings of primary tags and combinations of primary tags with one secondary tag. Neither combinations of several primary or secondary tags nor tertiary tags are covered so far. What this means exactly i will explain in more detail in the following.

The underlying tagging model

In principle OpenStreetMap uses a free form tagging system – i have discussed that in more depth in context of TagDoc. Practically, all OSM based map styles interpret this tagging in a somewhat more constrained fashion and because of that, mappers also tend to use tags under this somewhat more constrained tagging model.

In this model (as documented on TagDoc) tags are roughly divided into

• primary tags – those are tags that provide semantic meaning to a feature even if they are applied alone.
• secondary tags – those are tags that only have a well defined meaning when applied in combination with a primary tag.

In the context of map rendering and therefore StyleInfo, primary tags are tags that alone – when applied to some geometry – influence the rendering result. That would be tags like natural=water on polygon geometries, highway=motorway on linear ways or amenity=pub on nodes. Secondary tags are tags that modify the rendering of a primary tag. Examples are name=* on any of the previously mentioned primary tags or bridge=yes on highway=motorway.

Practically, there are some cases in styles that do not follow that model. For example administrative boundaries are rendered by most map styles only if they are tagged with both the primary tag (boundary=administrative) and with an admin_level=* tag (in case of OSM Carto with admin_level between 2 and 10). That requires introducing a third type of tags into the tagging model:

• qualifier tags – those are secondary tags without which the primary tag is not interpreted by the style.

In addition to the mentioned example of administrative boundaries, the most common qualifier tag is the name tag on features a map style renders with only a name label.

Note different map styles make different assumptions on what are primary and what are secondary tags – which poses additional difficulties on the analysis. OSM Bright and also OSM Carto in early versions interpret name=* as a primary tag and render name labels for anything with a name tag even in the absence of any other tags.

And as said – what StyleInfo so far does not cover is combinations of several different primary and secondary tags – which is interesting to look at because sometimes styles distinctly render such combinations (like a road with a bridge tag and access restrictions) while in other cases one tag shadows another (like most cases with several primary tags). What is also not covered is tertiary tags – that is cases where a three tag combination leads to a distinct rendering result – like in OSM Carto certain values of denomination=* in combination with religion=christian on amenity=place_of_worship changing the symbol used.

The principal limitations

Some might have already wondered about the selection of styles featured currently on StyleInfo. As you can see with the Map Machine style the analysis is not limited to CartoCSS/Mapnik styles. However, because of the large number of tests that needs to be run it is necessary that integration tests of the full rendering chain can be run efficiently on general purpose hardware in a headless configuration. And that is difficult for all of the postmodern client side rendered styles popular these days. If anyone can point me to a toolchain that renders Maplibre/Mapbox JSON styles into plain image files on headless general purpose hardware without depending on esoteric bloat like npm or docker i might give it a try.

For OSM Carto and other styles with a rendering database that directly reflects OSM tagging without any fancy tag reinterpretations on import, the map style analysis can be made quite a bit faster by excluding the database import step from testing. This underlines my past observation that the idea of performing tag interpretations on data import instead of during rendering – a consideration that has gained quite some popularity recently in the OSM community – is a bad idea from the perspective of map design. You gain nothing of substance (because tag interpretation is cheap) and it requires the map designer to either integrate the database import into their design work and testing (just like i need to do for the StyleInfo analysis) or to develop their style not for OSM data but for an intermediate data model out of their control (which is what most of the postmodern client side rendered style development tends to do – hence probably the popularity of that idea).

A viable map key?

What StyleInfo documents is how a map style translates OpenStreetMap data and tagging into a visual depiction. While this is evidently a key element of producing a usable map key or legend it lacks the translation between the OpenStreetMap tagging and real world semantics to qualify as such. This is – as some readers might remember – what TagDoc is aiming at. StyleInfo and TagDoc are projects complementing each other and the idea is that those two together could be key components to provide a much better understanding of the semantics of OpenStreetMap data and of OpenStreetMap based map styles to a wider audience.

Tags interpreted by OpenStreetMap Carto – visualization from StyleInfo, click to see interactive version

This post’s subject is a matter i have been working on for quite some time – the problem of systematic testing in map design. To make clear what this is about i will have to explain a bit the wider context.

Traditional testing in map design

The traditional way of designing rule based map styles, in particular in the OpenStreetMap context, is to do so based on a test database containing a sample of actual map data. Most map designers have a test database, typically containing either an extract (like from Geofabrik or created with the Overpass API) of their area of interest or a number of areas from different parts of the world. You can get an idea of the content of my test database through the ac-style sample gallery.

When you work on the design of a certain type of feature you find one or more occurrences of this in your test database and study the effects of your design work on these occurrences. Commonly used design tools – like TileMill in the early days, or Kosmtik (in case of CartoCSS styles) and other tools, like Maputnik, in case of JSON based styling languages – are specifically designed for this workflow.

Many examples of use of this approach in style development can be found in OSM-Carto – like here.

This design work strategy has several advantages:

• It is fairly straight away and does not require significant work from the designer to get started.
• It tests the design in exactly the context it is meant for, that is rendering of actual map data.

But it also inevitably comes with disadvantages:

• You only test the design in those contexts you happen to have picked as sample occurrences. That usually neither covers all the relevant situations the design is going to be used in nor is it representative for the full diversity of locations that feature occurs in.
• It is very difficult to do any sort of systematic testing. Even the comparison across different zoom levels is difficult because the geometric context changes in scale as you change zoom levels.

Synthetic tests

Because of these problems OSM-Carto developers have for a long time and in addition to the traditional testing based on real world test data started using synthetic tests. I can’t say for certain when this was done the first time but here are two examples:

Typically such tests are designed in JOSM, run through osmium renumber and then imported into a test database.

This kind of test is particularly useful for somewhat more experienced map designers who can already predict in advance in what contexts a certain change is in particular critical to be evaluated in.

I would go as far as saying that changes of the road rendering system in OSM-Carto, that often need to work in many different design contexts, are almost impossible to develop without the use of synthetic tests. The unpaved road rendering that recently finally made it to OSM-Carto is a good example for that:

As useful as this kind of testing is, it also bears the risk of map designers completely focusing on synthetic tests and neglecting testing with real world data. That is of course not a good idea. In practical map design real world data testing is always necessary and important.

The other issue is that with this kind of hand drawn synthetic tests you still have the problem of limited comparability across zoom levels.

Automated scaling of tests

This limitation has led me a few years back to develop an approach to scale synthetic test data sets in an automated fashion for better cross zoom level comparability. I have shown samples using this approach on several occasions on this blog. By scaling the test data to the zoom level you want to test at you make rendering results much better comparable across zoom levels. This is in particular useful to make sure that design parameter progressions across zoom levels (like line widths or label sizes) are working well.

Road features at z16

Same at z17 with scaled geometries

Systematic testing

Once you have automated scaling of tests working, it is only a small additional step to systematically test rendering results across zoom levels and with different combinations of attributes. This allows two things:

• formally testing map design in all the different variants it is supposed to work in.
• documenting the functions of a map style in a comprehensive fashion.

The latter use case is something i already demonstrated some time ago in TagDoc:

Lately i have further developed the whole concept of systematic map style testing into a tool i am going to introduce in the next blog post.