Simple 3D Buildings

This page describes tags for basic 3D attributes of buildings. This description scheme is therefore limited, not all details can be described by it. You can report cases of complex edits on the talk page or consult the page F3DB (Full 3D Building) for 3D mapping proposals advanced.

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 (building=*) for the most general area of a complex building and 2) building parts (building:part=*) to describe sections of the building, especially those with different height or other attributes.

How to map

Building outlines

Two building:part areas (green) within a building area (red). Gaps between polygons are illustrative only, in reality their sides match precisely.

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 this building outline. A building should have a single tag building=*, multiple buildings should not overlap.

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.

Building parts

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 (example building=yes, building:part=government and building:part=school if a building has a part used by the town hall and a room used as a classroom).

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 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.

Building relations

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.

Tags for buildings/building parts are classified into 3 categories:

• tags for only the roof of the building = tags with the prefix roof:
• tags for only the building under the roof (the facades) = tags with the prefix building:
• tags for both = tags with no prefix

Tags for both building facades and roof

Schematic example of level and height tagging

Key	Comment
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. See the section below for a good understanding of this tag and the usage of roof:height, building:levels and roof:levels.
min_height=*	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.

Tags for only the building facades under the roof

Key	Comment
building:levels=*	Number of floors of the building above ground (without levels in the roof). Allows you to texturize the building in a simple way because some 3D renderings add rows of windows for each floor. If you tag new buildings, try to give a height value. Try to use building:levels=* only in addition to a height tag! See the section below for a good understanding of this tag and the usage of height=*, roof:height=* and roof:levels=*.
building:min_level=*	Levels skipped in a building part, analogous to min_height
building:material=*	Outer material for the building façades.
building:colour=*	Colour of the building façades. See colour=* for possible values.

Note: there is no tag for the height of the facades (no tag building:height). This value is automatically calculated as the building's total height=* minus roof:height=*.

Tags for only the roof of the building

Roof shape

You can characterize the roof shape of a building using a catalogue of well-known roof types.

Image
roof:shape	flat	gabled	gabled_height_moved	skillion

Image
roof:shape	hipped	half-hipped	side_hipped	side_half-hipped

Image
roof:shape	hipped-and-gabled	mansard	gambrel

Image
roof:shape	pyramidal	crosspitched	sawtooth	butterfly

Image
roof:shape	cone	dome	onion	round

Other common values

Value	Comment
many	Marks that building has multiple different roof shapes at once. It is discouraged to use it because it is useless for rendering (roofs with this value are rendered as flat). Instead, use building:part=* carrying own roof:shape values. History described in detail in roof:shape=many.

Other roof tags

Key	Comment
roof:height=*	Height of the roof, from the top of the facades to the top of the roof. See the section below for a good understanding of this tag and the usage of height, building:levels and roof:levels.
roof:levels=*	Number of specific floors within the roof only. See the section below for a good understanding of this tag and the usage of height, roof:height and building:levels.
roof:angle=*	Alternatively to roof:height=*, roof height can be indicated implicitly by providing the inclination of the sides (in degrees).
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: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:colour=*	The (dominant) colour of the roof. Useful in conjunction with roof:material=*.
roof:material=*	The outermost material of the roof. Useful in conjunction with roof:colour=*.

Usage of height, roof:height, building:levels, roof:levels

There is currently an incompatibility between the meaning of the tags *:levels in 2D and 3D representations.

In 2D, they designate the number of floors of the part: 1 floor, 2 floors... 5 floors, etc.

In 3D, when height tags are not used, the tags *:levels, in the 3D rendering, are converted to simulated heights. Each floor is converted into a 3 meters high rendering.

For example, building:levels=3, roof:levels=1, no tag height=*, no tag roof:height=* will be converted in the 3D rendering into a 12 meters height building with 9 meters under the roof and 3 meters for the roof.

Therefore users can used decimal numbers for levels to have a good height. For example, in taginfo, you can find building:levels=1.5, roof:levels=0.5 or roof:levels=0.2! But what does "0.2 floor" mean in a 2D description of the building?

Rather than using decimal values, add the building heights. You will thus have compatibility between 2D and 3D information.

Example:

• rather than building:levels=1.5, roof:levels=0.7, no tag height=*, no tag roof:height=*,
• use building:levels=1, roof:levels=0, height=6.6, roof:height=2.1

Explanations:

• 1.5 building levels and 0.7 roof levels probably mean 1 useful floor for the building facades and no useful floors for the roof
• 1.5 + 0.7 = 2.2 floors in total = a height of 6.6 meters for the entire building (using 3 meters for each floor)
• 0.7 roof floor = a height of 2.1 meters for the roof

Notes:

• actual building heights are likely unknown for 99% of buildings in OSM. The value 3 meters for a floor is a default value, probably very close to reality for most of these buildings, and will display a good 3D rendering consistent with buildings without height tags. But of course if you know the real heights, use them!
• in some cases both are clearly necessary. For example for a sports hall, the building levels value is usually one (one floor and one ceiling) but the height is higher than the default 3 meters, so you need to add the actual height (for example building:levels=1, height=6). Please do not use a false 2 levels value to simulate a 6 meters high building if the building only has 1 ceiling!

This section is a wiki template, editable here.

Roof terminology

This image can help to understand some architectural terms.

Diagram of the main architectural elements that make up a pitched roof

3D examples

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

See also these models.

Software support

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.

Editing tools

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

Map applications

Application name	Platform	Schema support	License	Notes
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.
Cesium OSM Buildings	Web	partial		Updated monthly.
F4 Map	Web	yes	Proprietary	Demo Web Map with rendering and scene support
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). Rendering example.
Organic Maps	Android	partial	Proprietary	Height of buildings is rendered based on height tags (if set) or levels tags. Roofs are flat.
OSM2World	Windows, Linux, Macintosh	partial	LGPL	Currently implementing the remaining features for the 0.2.0 release - slippymap (Germany only)
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.
OSM Building Viewer	Web	partial	BSD	Visualizes an individual building based on live OSM data.
OSMBuildings	Web	partial	BSD
OSM go	Web	partial	GPL	Only pyramidal and dome (yet, flat is default)
Streets GL	Web	yes	MIT	Updated manually.
VR Map	Web	partial	MPL	Heights and colors only.
WikiMiniAtlas	Web	partial	GPL	Only pyramidal roofs.

Map frameworks

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 C++	Windows, Linux, OS X (Macintosh)	C++
CartoType for iOS	iOS	Objective C, Swift
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	partial	BSD	Options for customizing 3D building display are included in the Mapbox Style Specification. (See Mapbox's blog post announcing GL JS support.)
Mapbox GL JS	Web	JavaScript
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
node-mapbox-gl-native	Node.js	JavaScript		BSD
osm2x3d	Web		partial	?	see also [1] and [2]
OSMBuildings	Web	JavaScript	partial	BSD	2.5D and 3D versions available
Tangram	Web	JavaScript	partial	MIT	Mapzen renders 3D buildings in Tangram and other products
Tangram ES	Android, iOS, Linux, macOS	C++
VTM	Android, iOS, Web	Java	partial	LGPL	Part of the mapsforge project.

Design tools

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.

Related Proposals

• F3DB (Abandoned Full 3D buildings proposal)

See also

• windows=* - Describes whether a building(part) has windows.