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 and attribution 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, the count of boundary-excluded buildings and any source-selection details.

  • 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. Keep attribution and licence evidence in source_attributes.

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

Routing and identity#

  • covers(latitude, longitude) restricts explicit selection; auto_covers restricts only automatic routing. 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.

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