Anton Khorev's Diary

Problems with level

Posted by Anton Khorev on 15 November 2018 in English (English).

There are problems with `level=*` tag stemming from the fact that not all mappers agree on what it means. This problem comes up more often in some geographic areas than in others where different floor numbering traditions exist. In this sense it is like `name=*` tag where certain parts of a name stop looking like parts of a name after being translated into a different language.

So what are exactly the problems with `level=*`? Some people think that the value of this tag should be whatever floor number that is used in place. You can usually but not always read it off some plaque, floor plan or elevator button. Other people think that the value should be a number such that the first floor at or above the ground level gets number 0, the floor above it gets 1 and so on. Those two different ways of assigning a value could be exactly the same, especially for English-speaking areas where they have a “ground floor” as `level=0` and a “first floor” as `level=1`. If you are from those places, you may not even understand that there’s a problem. If you are from a place like Russia or the US, it’s evident for you that those ways are different. I’ll be using Russia as an example because it’s where I map.

But there should be no debate about the exact definition of `level=*` tag because we have a wiki where it’s perfectly documented, right? Not quite. First of all, we don’t have one wiki, we have multiple wikis in different languages. Those languages may correspond to areas with different floor numbering traditions, which in turn affects the wiki contents. Again, this is like `name=*`, where local wiki editors put their preferred spin on what should and what should not be part of a name.

Even if we stick to English wiki, we still won’t avoid the problems with its current contents. You may get different impression on what `level=*` actually means depending on where you start and where you end reading the page, and also whether you follow the links to certain other pages or not. In fact, since I mentioned other pages, how do you know which wiki page you have to read in the first place? You may think that it’s obviously Key:level, but that page disagrees with you, sending you elsewhere for further information. You may also remember `building:min_level=*` tag which also takes on level as a value. Or is it a different level? Is there a definition of level that exists independently of particular tags?

What can those disagreements lead to? We can look at this from the point of view of a data user and of a data editor. For a user, let’s say you want to get to a POI which is inside a building. You look it up in some app, for example OsmAnd, and the app would tell you which floor the POI is on. So you see among other things about the POI something like “Floor: 1”. Actually, OsmAnd will say “Level: 1”, but that’s going to happen if you have English interface. In Russian it’s going to be “Этаж” which is literally a floor. At this point we can remember what happens to the wikis in different languages and look at this as an attempt to bolster a particular interpretation of `level=*` through localization. I’m talking about level tag because the number you see in the app comes from this tag. As a user, you may not know anything about tags and possible differences in their interpretations. Your most likely interpretation of the number you see is going to be that it’s a floor number, a designation of a floor inside the building, which is either evident from local traditions or directly written somewhere. You are unlikely to attempt to determine level zero and then count the specified number of levels upwards. In fact, this counting operation may seem unnecessarily complicated and even nonsensical, which looks like a good argument to just use the self-evident floor number as a value of level tag. With this assumption you’ll only get the correct floor number if the last editor of level tag on the particular POI shares this opinion. If not, in Russia you’ll most likely end one level below the POI. Sometimes it’ll be two levels. It’s going to happen when “first floor” is slightly below the ground. In some cases the level will coincide with the floor number even under this “counting” interpretation, but you wouldn’t know that in advance.

What are the problems for editors? Obviously, different people may want different values for the same tag on the same object. This may lead to edit wars. You may then propose to keep whatever level numbering scheme already exists in a certain building and make everyone follow this scheme. Unfortunately this is not always possible. In order to know what scheme is in place you have to find stuff that is already mapped with level tag and figure out what scheme it corresponds to. There’s a chance that no single scheme would fit because different things were mapped by people with different opinions. This is likely to happen if there are many elements tagged with level. On the other hand there could be few and you wouldn’t notice them. All this scheme guessing has to be done because nobody indicates what scheme is to be followed at a particular place. Nobody indicates that because according to most mappers there’s only one right scheme and other schemes shouldn’t exist.

Even if you know the scheme, you can find yourself in a situation where you have to change already existing level values. For example, you may tag all of the POIs along a street in one manner and eventually you get to a place that was mapped differently. Do you stop and change your way starting with this place? Do you go back and retag everything you already have entered? If you have entered a lot and there’s only a few things mapped differently, it makes more sense to retag those few things.

Of course having two different interpretations of one tag is inconvenient. We are better off with just one that makes more sense and is easier to use. And we already know which one it is. Just write the local traditional floor number, you can always check it on place, you don’t need to figure out where’s level zero, you don’t need to count floors, you don’t need to follow the rules made up by foreigners who don’t know how things work in your country. That’s how people who prefer this particular scheme think, however there are reasons to think otherwise.

That other way of thinking goes as follows. We had the definition of level that has 0 assigned to the first level above the ground level for at least seven years. This definition is used in Simple 3D buildings (S3DB) for about as long. All of the software that uses S3DB data relies on this definition. It would be inconvenient to come up with another “indoor” level numbering scheme. It may not even be a numbering because floors can be designated by letters and then you wouldn’t know the vertical order of levels without extra data. Even some of software that mainly concerned with indoor visualizations like OpenLevelUp assumes 0-based numbering. So there is only one scheme that works, it’s been around for a long time, and it’s how it defined in the wiki. That last statement about the wiki is a bit of a wishful thinking done by the proponents of this scheme.

Those were the ideas behind the two major level numbering schemes: locally-defined labeling (it’s may not be strictly numbering) and 0-based numbering. As you can see, the proponents of these schemes can be pretty convinced that their scheme is the correct one and they want the level tag for themselves. In addition you can come up with many more schemes. For example, you may want 1-based numbering where you say that those who think that ground floor and first floor are two different floors got their traditions wrong and have to adapt to 1-based counting because all normal people count from one.

One noteworthy scheme lies between the two major ones. A scheme that we’ll call locally-based numbering attempts to fix some issues with locally-defined labeling. It uses only numbers that make the vertical level sequence well-defined. For this scheme you replace all non-numeric level labels with numbers. For example, if a building had level K below level 0, like described in this comment, you replace K with -1. Usually it’s the same as matching the number sequence …, -2, -1, 0, 1, 2, … as close as possible with all numeric labels. In this case the result is usually going to be the same as picking either 0-based or 1-based numbering, whatever fits best.

There’s one extra quirk that is skipped levels. Imagine a 100-storey building without 13th floor. The best match with the sequence would involve setting `level=2` for 1st floor, `level=3` for 2nd and so on until 12th floor. This is not what people typically want to do so it’s fixed by extra hack. This hack can be added to any of the numbering schemes mentioned above. It consists of declaring some of levels as non existent and their numbers are thrown out of the sequence before it’s matched with numeric labels. It also makes level numbers incompatible with S3DB levels, in case you use it with 0-based numbering.

For places like Russia, no matter what scheme you pick, you lose either compatibility with existing tools or traditional floor numbers, maybe both. Losing traditional numbers is particularly annoying because you have to use numbers that are almost always one off and it’s easy to make mistakes because of that. I think that compatibility with tools is the main divide here. Those who use S3DB want to see the visualizations with tools that assume 0-based numbering. After a while they get somewhat comfortable with that scheme and are more likely to stick with it for other things. Those who don’t use S3DB see 0-based numbering as something alien.

How prevalent are the problems described here, are they worth your attention? In the place I map, Saint Petersburg, Russia, both main schemes are in use. That means you can’t rely on levels displayed by apps like OsmAnd. I’ve seen levels changed from one scheme to another when next user comes to edit elements with existing level tags. I had to do it myself too, in the situations I described above. Now I mostly avoid the buildings such as malls that are mapped using the other scheme, but eventually I’ll have to do something about them. I haven’t yet seen full-blown edit wars over level values, however currently there’s nothing that would stop one from happening.

What’s to be done about it? You can do something about the editing apps, the end-user apps and the tagging conventions with their documentation. That last thing is going to be the subject of another post, but I can tell right away what can be done with the editors even if we don’t agree on the exact meaning of level tag. This is for editors with indoor mode such as Vespucci. In this mode you don’t have to enter the level values directly, the editor sets them for you. You only have to select the level to be displayed. The level selector can be modified to display some other number instead of the actual level value, or display both actual and altered values alongside each other. The simplest way to specify how to alter the value is to have the level offset option that takes numeric values. For example, with the +1 offset, `level=0` would be displayed as 1. A more elaborate options would be required to skip (or insert) certain numbers and replace numbers with letters (or letters with numbers), but the simple offset would solve a lot of problems.

I tried to write this post from neutral point of view without preferring any particular scheme. You can read about my opinion on which scheme is better and which one do I use in my previous post (in Russian). It’s quite long, but you only need sections Вертикальная геометрия and Как я маплю. The next thing to be discussed about levels is what exactly the wiki says. I’m going to leave it for another post.

Comment from bryceco on 16 November 2018 at 03:07

Yes, this is spot-on. It’s confusing having to convert elevator/directory floor 3 to level 2. And many buildings are built on a grade and have entrances on multiple levels, so it makes the definition ambiguous whatever choice is made.

Comment from SimonPoole on 16 November 2018 at 08:14

There is already a level:ref tag defined in SIT that can be added to the level outline for level names or very different numbering.

PS S3DB doesn’t have a level tag and when the concept of levels is used it is as a proxy for the height of the element.

Comment from Severak on 16 November 2018 at 09:37

For me it only logical thing is to use same numbering as building itself. But it seems that this is done with level:ref.

Comment from Polyglot on 23 November 2018 at 08:49

Этаж comes from French étage, by the way.

Comment from Polyglot on 23 November 2018 at 09:04

As a European it has always struck me as weird to say that the ground floor would be the first floor.

Where does 0 fit in for those who count that way?

Polyglot

Comment from Stalfur on 25 November 2018 at 20:56

As a European the ground floor is the first floor….

Comment from SimonPoole on 25 November 2018 at 21:12

@Stalfur I think you will find major parts of Europe disagree with you.

In any case as I’ve pointed out differing numbering schemes etc, can be recorded in level:ref

Comment from Stalfur on 25 November 2018 at 23:06

@SimonPoole They might, and does that make them right?

Comment from -karlos- on 26 November 2018 at 06:42

In German it is “Erdgeschoß” (ground floor) and “Erster Stock” (first … what?)

• “Geschoß” sounds strange already. It is “rise” or “towering” the first building level, build on top the ground.
• “Stock” means “top up”, build another “floor” on top of the first one.

So ground floor is first floor to me. But the next abowe is the first level to me. It’s like writing code with arrays. The first index is 0. We should have free level names but a defined level numbering, starting with 0. But what, if threre is only a tag “level” with a numerig value? For a “level_name” or “level:name” is the “level:ref” tag already.

For walking navigation and 3D rendering we need a defined concept! But I als agree, it is strange to always substract 1. Just an Idea: Could we thing of it as an mesurement unit? Zerro based units vise first based units? By adding a dot: The tag string is either a plain (or multible) integer value or it is a string with a dot added. So “1.” means the same as “0”.

Comment from Mateusz Konieczny on 26 November 2018 at 16:08

@Stalfur Not in, for example, Poland.

Comment from Stalfur on 26 November 2018 at 16:13

Someone asked “what is level 0 to you” and that is quite simple really.

Personally I’ve never discussed level 0 buildings, when I map if I’m asked how many levels a building is I count from 1 because I’m not counting items in a programmable array where we start with 0. If you answer “It is 3 plus ground floor” then do you put 3 or 4? Do you do addition or do you IMPLY the addition and everyone should know it?

Comment from westnordost on 26 November 2018 at 21:36

Thank you for the long treatise on the confusion about the level tag. But at the same time I am relieved to see it disarmed by such a short comment from @simonpoole about level:ref.

No matter how confusing the level tag may be in countries with different numbering traditions and how tempting it may be to use the levels as displayed on the elevator instead, it is an absolute no-go in OSM to change a definition of a tag after it has been established, also not by “country-wide consensus”. Instances where the tag is not used as defined in the wiki are simply wrong and must be corrected.

That being said, this blog entry and sime of the comments here are a sign that the situation could be improved:

1. Improve the wiki documentation to be crystal clear on the levels and levels:ref tag, also on translated wiki pages in other languages
2. Improve software support for entering and displaying the value of the level tag and level:ref tag in the correct localized version. Maybe share a tiny library or code snippet to facilitate this. This topic actually just came up on StreetComplete.

Comment from 4004 on 29 November 2018 at 00:05

One of the most annoying things about free for all that is wiki documentation, made even worse when I switch from mapping in one country to another where 70% put a different spin on the level tag “because it doesn’t make sense”. I think the community would benefit immensely if the wiki was cleaned up and clear cut

Comment from SimonPoole on 30 November 2018 at 15:37

The discussion is getting slightly silly now. We had to choose a default numbering and regardless of which one we would have chosen somebody would have been unhappy.

That said the schema with the ground floor/parterre being numbered as 0 or not at all, and the 1st floor up being number 1 is really very common with literally millions of building being numbered that way.

If regionally your level numbering skips 0 for the ground floor, aka goes directly from -1 to 1, you can simply add non_existent_levels=0 to the building outline and apps that are aware of this will not display 0 as a choice.

Comment from batyrmastyr on 4 December 2018 at 12:58

Simon, in one of the first proposals there was “levels” tag containing ordered list of existing floors. For example “P2,P1,G,1-12,14-99” defines a building without zero and thirteenth floors. In fact, it also allowed to define height of each floor in meters.

Simply adding tag ground_floor=1 gives us a simple way to understand that P2,P1 and G are all underground and we need to render 98 storey building. No mindblowing level calculations, no workarounds for non_existing_levels. 3 years before SITh, just add one simple tag and have superfast rendering as you don’t need to traverse all intersecting level relations or objects, all you need is building itself.

Comment from SimonPoole on 4 December 2018 at 13:02

Except that there was and is already the widely used builiding:levels tag meaning something completely different.

Comment from westnordost on 4 December 2018 at 14:56

Batyrmastyr, that sounds pretty nice, actually. It allows the level tag to be used correctly 0-index-based as specified while offering an intuitive solution to tag how the levels are denoted in a building (though that proposal you linked is pretty TLDR).

With what Simon suggested to use earlier, the problem is solved, but the level_ref then needs to be copied onto every single shop/indoor thing. Also, the non_existent_levels(=13) tag is somewhat unintuitive because it is not clear from the name whether it is a tagging mistake to tag any shop with level=13 within that building or whether some shop tagged as that is actually to be referred to be in the 14th floor. Both options are unintuitive.

Comment from batyrmastyr on 4 December 2018 at 15:15

`building:levels` is a different tag with different purpose, so there is no real issue.

was and is already the widely used builiding:levels

I’ve found only 2 proposals with `building:levels`: Simple 3D Building since 2012 and “Building Attributes” since 2008, but it was partly broken by 2011 and it’s hard for me to say was it widely used or not. Oh, authors of S3DB has broken this tag: “Number of floors of the building above ground (without levels in the roof)” is quite different from “Number of stories, including the ground floor”. Shame on them.

If regionally your level numbering skips 0

In fact, there are (1) buildings on hills with many “ground” levels (2) some buildings have their own floors naming scheme. For example, nearby trading center hit both: floors numbered as “-2”, “-1”, “1” and “2” with parking on “-2” and shops on the others. To make things more funny, floors “-2”, “-1” and “1” are on the ground.

So, from my point of view, ignoring “truth on the ground” principle made `level` tag broken for indoor mapping without relations and should be forbidden in favor of `level:ref`.

Comment from westnordost on 20 January 2019 at 13:56

I posted a research about the actual use of the level tag on the tagging mailing list.

Also, I found out that according to the wiki, `level:ref` is actually only mentioned in context of tagging the floors in indoor mapping, not for tagging the level of individual shops.