Simple 3D Buildings
This page describes tags for basic 3D attributes of buildings.
The following tagging methods are results of the 2nd 3D Workshop Garching, where most 3D developers agreed on supporting a unified subset of tags in their programs. Basically, we describe the volume of a building using two types of areas: 1) building outlines for the most general area of a complex building and 2) building parts to describe sections of the building, especially those with different height or other attributes.
How to map
The building outline represents the area of land covered by the union of all parts of the building. The outline may in most cases also be considered the building footprint. This is a closed way or multipolygon tagged with building=*.
Building attributes (e.g., address, name, overall height, operator, etc.) must be tagged on the building outline.
The building outline provides backward compatibility for 2D rendering software, such as Mapnik, and other data consumers not interested in 3D modeling. When a building has any building:part=* areas, the building outline is not considered for 3D rendering.
Parts of a building that have differing physical characteristics (height, color, etc) are usually modeled by drawing an area within the building outline tagged with the building:part=* tag. The value of the building:part=* tag is usually yes, but it can be any building=* value.
The entire building outline should be filled with building:part=* areas, tagged with their respective height and other attributes. These areas may overlap each other or may be disjunct, depending on the building. That said, while 2D footprints can (and often need to) overlap, avoid overlapping 3D volumes – especially if the volumes have common faces.
See the following section for building attribute tags typically applied to areas tagged with building:part=*.
Areas tagged with building:part=* are mainly considered for 3D rendering. 2D renderers ignore the building attribute tags described in the following section.
Tip: Overlapping shapes like this can be tricky to select. In JOSM, click while holding down 'Alt' key to cycle through overlapping objects and make the selection you want.
If at least one part of a building is hanging over the building footprint or if the building has a complex structure with lots of parts, a type=building relation can be used to group the building outline and all building parts together. Otherwise, there is no need to create a type=building relation, i.e. simply position all building parts inside the building outline as described above.
If the type=building relation is present for a building, all building parts must be listed as the relation members with the role part. The building outline must be listed with the role outline. The building parts can be located in any possible way (inside, outside, intersecting, touching) relative to the building outline in the presence of the type=building relation.
If there is no type=building relation, an application should treat all building parts within the area of the building outline as part of that building.
Tagging for building outlines and parts
The following tags can be used on both building outlines and building parts.
Height and levels
|height=*||Distance between the lowest possible position with ground contact and the top of the roof of the building, excluding antennas, spires and other equipment mounted on the roof.|
|min_height=*||Approximate height below the building structure.|
Note that when min_height is used, height is still defined as the distance from the ground to the top of the structure. So "bridge" with 3 meters height, where bottom part of the bridge is positioned 10 meters above ground level will have min_height=10, height=13.
|building:levels=*||Number of floors of the building above ground (without levels in the roof), to be able to texture the building in a nice way.
If you tag new buildings, try to give a height value. Try to use building:levels=* only in addition to a height tag!
|building:min_level=*||Levels skipped in a building part, analogous to min_height|
You can characterize the roof shape of a building using a catalogue of well-known roof types.
Other common values.
|side_hipped||Half of a hipped roof, not the same as half-hipped. One vertical gabled side, one 'hip' with three sloped faced. This is common on semi-detached properties where the whole building has a hipped roof, but each house has a side_hipped roof.|
|many||Marks that building has multiple different roof shapes at once. Such building may have building:part=* carrying own roof:shape values. History described in detail in roof:shape=many|
value with problems
|saltbox, double_saltbox, quadruple_saltbox||conflicting definitions and meanings of "saltbox" in this context. |
|conical||duplicate of cone|
|lean_to||Unclear, probably should be skillion.|
|shed||Mono-pitched roofing, also sawtooth|
|gabled_row||Unclear, sometimes used on a sawtooth roof, sometimes a row of gabled terrace.|
|roof:orientation=along/across||For roofs with a ridge the ridge is assumed to be parallel to the longest side of the building (roof:orientation=along). But it can be tagged explicitly with this tag.|
|roof:height=*||The height of the building (i.e. the height of the façade) is calculated as the building's total height=* minus roof:height=*.|
|roof:angle=*||Alternatively to roof:height=*, roof height can be indicated implicitly by providing the inclination of the sides (in degrees).|
|roof:levels=*||Number of floors within the roof, which are not already counted in building:levels=*.|
|roof:direction=*||Direction from back side of roof to front, i.e. the direction towards which the main face of the roof is looking.|
|roof:material=*||The outermost material of the roof. Useful in conjunction with roof:colour=*.|
|roof:colour=*||The (dominant) colour of the roof. Useful in conjunction with roof:material=*.|
Some roofs (e.g., square buildings) cannot be accurately modeled with the simple techniques described on this page.
Additional roof shapes are suggested in S3DB Proposals, including advanced approaches for manual modelling (e.g., ProposedRoofLines or parts of OSM-4D/Roof table).
This section is a wiki template, editable here.
Surface color and material
|building:colour=*||Colour of the building façade. See colour=* for possible values.|
|roof:colour=*||Colour of the building roof. See colour=* for possible values.|
|building:material=*||Outer material for the building façade.|
|roof:material=*||Outer material for the building roof.|
To view numerous 3D buildings on a large scale, see examples here: 3D Demo Areas
To view individual 3D buildings, see examples here: 3D Building Examples
- Main article: 3D development
Many maps and tools support the simple 3D buildings schema. Among the first were the OSM-3D.org renderer in 2009, the OSM2World renderer and Kendzi3D JOSM plugin in 2011, and the Nutiteq Android 3D Mapping SDK (now Carto Mobile SDK) and WikiMiniAtlas in 2012. OSMBuildings launched a 2.5D display in 2012, followed by a 3D version in 2015. In 2013, F4 Map became the first browser-based renderer to fully support the Simple 3D Buildings schema.
|Software name||Platform||Schema support||License||Notes|
|Kendzi3d||Windows, macOS, Linux||yes||BSD||JOSM plugin|
|SketchOSM||Windows||partial||Proprietary||SketchUp plugin in beta, discontinued July 2020|
|Application name||Platform||Schema support||License||Notes|
|OSM2World||Windows, Linux, Macintosh||partial||LGPL||Currently implementing the remaining features for the 0.2.0 release - slippymap (Germany only)|
|F4 Map||Web||yes||Proprietary||Demo Web Map with rendering and scene support|
|OSM go||Web||partial||GPL||Only pyramidal and dome (yet, flat is default)|
|Mapbox Static API||Web||partial||BSD||Requires a free Mapbox Studio account.|
|OpenScienceMap||Web||partial||LGPL||Interprets only height/min_height tags client-side. The S3DB Layer uses vtm meshes generated on the server (using plpgsql with PostGIS and SFCGAL). Web map|
|CartoType Maps App||Windows, Linux, Macintosh||partial||Proprietary but unrestricted use||A free demonstration application for the proprietary CartoType library. The CartoType GL version implements most roof shapes. Includes a style sheet editor.|
|OSM-3D.org||Web||partial||Currently offline unless you have an older Java version (≤1.6). New WebGL version in development.|
|osmapa.pl Mapnik stylesheet||Web||partial||Most roof types implemented in 2.5D view.|
|WikiMiniAtlas||Web||partial||GPL||Only pyramidal roofs.|
|VR Map||Web||partial||MPL||Heights and colors only.|
|Cesium OSM Buildings||Web||Updated monthly.|
- Main article: Frameworks
|Software name||Platform||Language||Schema support||License||Notes|
|Carto Mobile SDK||Android, iOS, Windows Phone||Java, Objective-C++, Swift, C#||partial||BSD||most roof shapes supported; see Carto's documentation|
|CartoType for Android||Android||Java||partial||Proprietary||Most roof shapes supported.Styles can be controlled using CartoType's XML style sheets. Uses OpenGL ES graphics acceleration. Viewing angle, height, field of view, etc., can be modified.|
|CartoType for iOS||iOS||Objective C, Swift|
|CartoType for C++||Windows, Linux, OS X (Macintosh)||C++|
|CartoType for .NET||Windows||C#, VB.NET and other .NET languages|
|CartoType for Qt||Qt on Windows, Mac (OS X) and Linux||C++|
|Mapbox Android SDK||Android||Java|
|Mapbox iOS SDK||iOS||Objective-C, Swift, Interface Builder|
|Mapbox macOS SDK||macOS||Objective-C, Swift, Interface Builder, AppleScript|
|Mapbox Qt SDK||Qt||C++, QML|
|Mapbox Unity SDK||Cross-platform||C#||Apache|
|osm2x3d||Web||partial||?||see also  and |
|Tangram ES||Android, iOS, Linux, macOS||C++|
|VTM||Android, iOS, Web||Java||partial||LGPL||Part of the mapsforge project.|
|Software name||Platform||Schema support||License||Description|
|blender-osm||Windows, macOS, Linux||partial||GPL||One click download and import of OpenStreetMap and terrain. Can import more than 100,000 buildings. A large number of roof shapes is supported: flat, gabled, hipped (for a quadrangle outline only), mono-pitched, half-hipped, round, pyramidal, gambrel, dome, onion and saltbox.|
|Mapbox Studio||Web||partial||Proprietary||Includes a Mapbox GL style editor that supports building (part) heights.|
|Maputnik||Web||partial||MIT||A Mapbox GL style editor that supports building (part) heights.|
|Tangram Play||Web||partial||MIT||A Tangram scene editor that supports extruded buildings with heights based on OSM data.|
An image can help to understand some architectural terms.
- F3DB (Abandoned Full 3D buildings proposal)
- ↑ This doesn't apply to F4 Map, see: Non-building:part parts of buildings are not rendered #3, Streets GL GitHub, StrandedKitty comment, 3 May 2023
- ↑ blog.mapbox.com
- ↑ By some users/editors, the roof shape which is shown on this picture may be interpreted as double_saltbox, whereas saltbox then has only one upper roof edge.
- ↑ What is a saltbox?, Tagging ML, 12 Feb 2020