Commit 177a199a authored by Cecilia Nievas's avatar Cecilia Nievas
Browse files

Added initial documentation on occupancy classification

parent 63e2e3f7
Pipeline #27098 passed with stage
in 2 minutes and 12 seconds
# Determination of the Occupancy of OpenBuildingMap Buildings
## What is occupancy?
By "occupancy" we refer to what a building is used for. Classic broad occupancy categories can be, for example, residential, commercial, industrial, govermental, educational, etc. More specific occupancy categories can be, for example, a detached or semi-detached house, an apartment block, a hotel, a retail shop, a light industry, a primary school, and so on.
## What are occupancy strings?
In OpenBuildingMap we classify occupancy as per the [GEM Building Taxonomy v3.0]( In the GEM Building Taxonomy, occupancy strings consist of three letters, which point at the general class, plus a number and/or a combination of numbers and letters, which point at a more detailed class. For example, RES1 refers to a single dwelling residential building (e.g. a detached house) while RES2 refers to a multi-unit residential building (e.g. a semi-detached house, an apartment block). Explanations regarding the meaning of the occupancy strings can be found in this [glossary](
## How are occupancy strings assigned in OpenBuildingMap?
In broad terms, the steps followed are the following:
1. Retrieval of OpenStreetMap tags associated with the building.
2. Mapping of OpenStreetMap tags into occupancy strings as per the GEM Building Taxonomy.
3. Evaluation of rules that consider the whole group of resulting occupancy strings and decide on the final occupancy assigned to the building.
Diving into the details, the process starts for any particular building by retrieving three sorts of tags from the [OSM-Replication database](
- `building tags`: OpenStreetMap tags associated with the building polygon.
- `points of interest (PoI) tags`: OpenStreetMap tags associated with points of interest that are contained within the building polygon.
- `land use tags`: OpenStreetMap tags associated with polygons tagged as land use polygons (and not buildings) that are intersected by the building polygon.
There is no limit to the number of tags that can be retrieved for any individual building and all tags associated with a building (as defined above) are considered.
Once tags have been retrieved, they are mapped into occupancy strings as per the GEM Building Taxonomy with help from two CSV files: [building_and_PoIs_tags.csv](./rules/occupancy/building_and_PoIs_tags.csv) and [landuse_tags.csv](./rules/occupancy/landuse_tags.csv). The relationship between tags and occupancy strings is not perfect, as it is frequent that either the tags or the occupancy strings are not fully defined and there is room left for interpretation. Comments and suggestions that may improve the mapping are thus welcome.
All occupancy strings identified from this mapping stage are collected, grouped according to the type of tag that gave rise to them (building tags, PoI tags, land use tags). A series of rules are then run on these collections of occupancy strings and the final occupancy is finally assigned.
The first rule that is run consists in evaluating whether any occupancy string of a pre-selected sub-set is present in the collections of occupancy strings retrieved for the building and adopting that occupancy as the final one. This pre-selected subset is called the set of "overriding occupancies" and can be found [here](./rules/occupancy/overriding_occupancies.csv). The order in which the occupancy strings are named in the file is hierarchical: the first string takes precedence over all the rest, the second takes precedence over all the rest except for the first one, and so on. The logic behind this rule can be easily understood with the example of an airport. An airport building can be associated with tags of all kinds, including tags for restaurants, cafes, retail shops, offices, police, customs, etc. However, the building is still, above all, an airport, and thus the final occupancy should correspond to that of an airport.
Further rules for the assignment of final occupancy strings will be defined soon.
## Contents of the mapping CSV files
The files [building_and_PoIs_tags.csv](./rules/occupancy/building_and_PoIs_tags.csv) and [landuse_tags.csv](./rules/occupancy/landuse_tags.csv) contain the following columns:
- `key`: OpenStreetMap key.
- `value`: value of the key (together, `key=value` are a `tag`).
- `taginfo_description`: description of the tag according to [taginfo](
- `occupancy`: the occupancy string according to the GEM Building Taxonomy. If more than one value is possible, they are separated by "|".
- `comments`: comments associated with the established mapping.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment