Building-source plugins#

A building source is a BuildingSource record: an identifier, a title, an implementation version, a factory that builds an asynchronous provider, and optional coverage, routing, attribution and licence fields. Installed packages register one through the openworld_radio_twin.building_sources entry-point group; the entry-point name must equal the identifier.

Minimal plugin#

examples/building_source_plugin registers local, a source that reads a persisted source_buildings.json from any OWRT scene:

# pyproject.toml
[project.entry-points."openworld_radio_twin.building_sources"]
local = "owrt_local_buildings:building_source"
# owrt_local_buildings/__init__.py
from openworld_radio_twin.providers.base import BuildingQueryResult
from openworld_radio_twin.providers.registry import BuildingSource


class LocalBuildings:
    def __init__(self, path, digest): ...

    async def buildings(self, latitude, longitude, radius_m, limit) -> BuildingQueryResult:
        ...
        return BuildingQueryResult(buildings=selected[:limit], provider="Local building records")


def building_source() -> BuildingSource:
    return BuildingSource(
        identifier="local",
        title="Local building records",
        version=f"1:{digest}",
        factory=lambda settings, client: LocalBuildings(path, digest),
        auto_priority=None,   # explicit selection only
    )

Install it next to OWRT and select it like any built-in source:

python -m pip install -e examples/building_source_plugin
export OWRT_LOCAL_BUILDINGS=/absolute/path/to/scene/source_buildings.json
scene = owrt.load_scene(latitude=52.3762, longitude=4.8993, radius_m=250,
                        building_source="local", terrain="flat", device="cpu")

Restart the web server after installing a plugin; both page menus discover it from GET /api/building-sources.

Provider contract#

  • buildings(latitude, longitude, radius_m, limit) returns a BuildingQueryResult with the features inside the square domain, the provider name, an optional release string, warnings and the count of boundary-excluded buildings. OWRT records the resolved source identity.

  • Return BuildingFeature.geometry for native triangle shells with an explicit CRS, vertical datum, ground elevation, triangles and surface semantics; omit it to use footprint extrusion. Name the credit line and the licence in the source’s attribution, license and license_url; packaging refuses scenes from a source without a licence.

  • Raise BuildingProviderError for acquisition failures so the service reports 502 instead of an empty scene.

  • Name the credit line, the licence and its page in attribution, license and license_url; GET /api/building-sources lists them. MapDataProvider.buildings copies them into the BuildingQueryResult it returns, the scene keeps them in source_buildings.json, and a dataset scene lists them in its licences (Dataset layout).

Routing and identity#

  • covers(latitude, longitude) restricts explicit and automatic selection; auto_covers restricts only automatic routing. Use covers when the provider cannot tell that a query lies outside its data, and auto_covers when it checks its own tile index, as the Berlin and Boston sources do. auto_priority makes a source eligible for auto; None leaves it explicit-only. Higher priority wins among covering sources, and the eligible set is further limited by OWRT_AUTOMATIC_BUILDING_SOURCES.

  • A built-in source joins the default OWRT_AUTOMATIC_BUILDING_SOURCES only when its publisher’s terms let anyone use, adapt and share the data and results derived from it for any purpose, with at most attribution and share-alike conditions; it names them in license, license_url and attribution. A source without such terms stays selectable by its identifier, and a deployment may add it to the setting itself. The Boston OBJ downloads state no licence, so boston is not in the default list.

  • version participates in scene cache keys and dataset resume checks; increment it when the interpretation of the source or the geometry reconstruction changes. The example folds the file digest into the version so a changed input creates a distinct scene.

  • configuration_identity(settings) lets a source add local configuration, such as a catalog path and hash, to the identity recorded with every scene.

Providers are trusted installed code. For a large archive, replace the example’s in-memory scan and whole-file hash with a spatial index and a stable release checksum supplied by the source.