User:RicoZ/layer, level and rendering priority

From OpenStreetMap Wiki
Jump to navigation Jump to search

Draft, not to be proposed but description of current practice.

OSM is essentially a 2D map with various implicit and explicit methods to map overlapping and 3D features.


Features generally are mapped "on top of the flat earth". In most mappers thinking and by the means of various tools and renderers this "flat earth" is usually refined by elevation information, forming a 3D model of the flat earth. Only when features do not follow the "normal" ordering are additional tags used.

The "normal ordering" is roughly

  • ground, natural landcover like forests, meadows, rocks
  • water, waterways (those are above the ground which they flood!)
  • man made features (a house is built on top of a rock)

For technical and historic reasons mapping is also strongly influenced by the implicit node/way/area ordering. Here nodes are more specific than ways, which are more specific (or have higher priority) than areas. Hence if a river or a road cuts through an area most mappers and tools assume the linear feature will override/hide the area where they cut.

Very few natural features are above or bellow ground such as Proposed features/natural=cave which has an implicit location=underground but can be also mapped with a layer tag if needed.

Man made features

  • layer=* - define vertical relationship of distinct objects where they intersect or overlap
  • level=* - floor levels inside objects (or tied to a particular object)
  • covered=*
  • bridge=*, tunnel=* : should be used with layer but have an implicit above/bellow ground meaning
  • embankment=*, waterway=dam - have an implicit "above surrounding ground" meaning
  • location=* - see bellow


location=* can be used for both natural and man made objects that are bellow/above natural ground or located on top of man made objects.

Data consumers

An ideal 2D renderer could establish a 3D model of features, filter them by relevance (according to the purpose of the map) and visually compose the result according to 3D ordering and rendering priorities.

The 3D modeling is mostly determined by the natural (common sense) vertical ordering of features in combination with layer, level, location and other tags approximately in this order:

  • natural/common sense ordering: (location=underground, tunnel) under (landcover, landuse, natural) under waterways under (highway, railway) under (man_made, building) under (bridge, location=overground, location=overhead)
    • nodes are above ways which are above areas
  • layer tag value:
    • layer can only "overrule" the natural ordering of features within one particular group but not place for example a river or landuse above a bridge or an aerialway (exception: use in indoor mapping or with location tag)
    • layer tags on "natural features" are frequently completely ignored
  • level tag value: considered together with layer - layer models the placement of distinct man made objects while level is for features within such objects.

Legacy rendering conventions

Mapnik has/used to have the rule that if areas overlap the smaller one will be rendered