Building sources#

Buildings come from a registry of trusted, installed providers. The Python loader, the CLI, the HTTP API and batch requests all share the same resolver and accept the same building_source values.

Available sources#

ID

Title

Coverage

Geometry

Attribution and licence

overture

Overture Maps

worldwide

Footprint extrusion with height, min_height, num_floors

Overture Maps Foundation, ODbL 1.0, plus the upstream datasets and licences it names, recorded per scene

osm

OpenStreetMap

worldwide

Footprint extrusion from Overpass ways and relations

© OpenStreetMap contributors, ODbL

3dbag

3DBAG LoD2.2

Netherlands

Native LoD2.2 roof geometry

© 3DBAG by tudelft3d and 3DGI, CC BY 4.0

berlin

Berlin LoD2

Berlin tiles

Official CityGML LoD2 tiles (roofs, walls, ground surfaces, parts)

Geoportal Berlin / 3D-Gebäudemodelle LoD2, dl-de/zero-2-0

boston

Boston BPDA OBJ

Boston tiles

Catalogued BPDA OBJ models at their supplied level of detail

Boston Planning and Development Agency

GET /api/building-sources lists the sources installed in a running service, including plugins, with their attribution and licence. The explorer and batch pages build their menus from that list.

Automatic routing#

building_source="auto" (the default) picks a regional source from the scene centre using packaged official boundary polygons:

  • inside the Netherlands: 3dbag

  • inside Berlin: berlin

  • anywhere else: global, which queries Overture and falls back to OSM when Overture fails or returns no geometry

Selection follows the requested scene centre, not the visible camera footprint, so a neighbouring city such as Potsdam does not inherit Berlin’s source. building_source="global" overrides the regional defaults; an explicit ID selects one source. boston is selected only by its ID; Building-source plugins gives the rule.

A selected regional source that fails or returns no buildings is not silently replaced by global extrusions. 3dbag refuses a centre outside the Netherlands; berlin and boston restrict only automatic routing, so an explicit request can query tiles beyond the routing polygon and the provider’s tile index then determines availability.

The set of sources eligible for automatic routing is a setting, OWRT_AUTOMATIC_BUILDING_SOURCES, defaulting to 3dbag and berlin. Installing a plugin does not change automatic routing.

from openworld_radio_twin import rt as owrt

# Berlin LoD2 tiles, flat ground, CPU
scene = owrt.load_scene(
    latitude=52.519, longitude=13.404, radius_m=100,
    building_source="berlin", terrain="flat", device="cpu",
)

What is kept and what is recorded#

  • Scene boundary. Only buildings whose complete footprint lies inside the square ENU domain are kept. Boundary-crossing buildings are excluded and counted in provenance, which avoids both geometry outside the terrain and artificial walls created by clipping.

  • Heights. Overture height is the roof height above ground in metres and min_height the base above ground; the extrusion spans the difference. A missing height is 3.2 m per floor from num_floors; a building part without either takes its parent’s roof height; otherwise the height is 10 m with 5 m uncertainty. The basis is recorded per building.

  • Native geometry. 3DBAG, Berlin and Boston records carry triangle shells with their source CRS, vertical datum and ground elevation. Native roofs are kept in solver meshes, browser meshes, height maps, slices and voxels. Source-native coordinates and the terrain alignment are recorded separately. A shell is anchored on its ground faces; a part that has none, which 3DBAG emits occasionally, is anchored on the projection of its whole shell and records that rule in its placement provenance.

  • Placement. Buildings are positioned in metres above the sampled local terrain. A footprint extrusion is anchored at the minimum vertex elevation of the compiled terrain triangles it intersects, minus a footing margin. This is deterministic but does not reconstruct stepped or sloped foundations.

  • Identity. Every result records the requested and resolved source, its implementation version and, for sources with local configuration, a configuration identity. These values participate in scene cache keys and dataset resume checks.

  • Limits. Browsing and simulation enforce separate building limits (OWRT_MAX_VIEW_BUILDINGS, default 7,500; OWRT_MAX_BUILDINGS, default 5,000). Every built-in source stops at the limit, and the service reports when it was reached. Building records are cached in application memory only; a compiled scene keeps those it uses in source_buildings.json.

Boston catalogs#

By default the Boston source reads the public ArcGIS tile catalog for the official 2025-01-28 OBJ release. For offline use and historical studies, prepare a local catalog and point the service at it:

python examples/prepare_boston_archive.py --sample --output data/boston-2021/catalog.json
export OWRT_BOSTON_SOURCE_CATALOG=$PWD/data/boston-2021/catalog.json

A catalog records the release, tile bounds, coordinate origin, archive paths or URLs and mandatory archive hashes. Its identity enters the scene cache key, so a scene compiled from one catalog is never reused for another release.

Plugins#

Additional sources register through the openworld_radio_twin.building_sources entry-point group and become selectable by ID everywhere. See Building-source plugins.