Loading scenes

The Sionna-compatible loader

openworld_radio_twin.rt.load_scene accepts the same positional arguments as Sionna’s own load_scene and adds keyword-only geographic options. Passing a filename loads a scene file; passing latitude, longitude and radius_m compiles a geographic scene first. The two forms are mutually exclusive and the return value is always a native sionna.rt.Scene.

from openworld_radio_twin import rt as owrt

scene = owrt.load_scene(
    latitude=52.3762, longitude=4.8993, radius_m=250,
    cache_dir=None,               # default: .cache/scenes under the checkout
    buildings="auto",             # "auto" retrieves buildings, "none" skips them
    building_source="auto",       # see Building sources
    terrain="elevation",          # "elevation" | "flat" | "none"
    material_profile="itu",       # "itu" | "uniform"
    terrain_resolution_m=5.0,     # terrain mesh spacing, not DEM accuracy
    device="auto",                # Mitsuba variant: "auto" | "cuda" | "cpu"
    merge_shapes=True,            # forwarded to Sionna
)

Option	Values	Effect
buildings	"auto", "none"	Whether building geometry is retrieved at all
building_source	"auto", "global", "3dbag", "berlin", "boston", "overture", "osm", installed IDs	Which provider supplies the buildings (Building sources)
terrain	"elevation", "flat", "none"	DEM-following ground, a planar ground, or no ground geometry (Terrain)
material_profile	"itu", "uniform"	Semantic surface classes with ITU proxies, or one material (Surfaces and materials)
terrain_resolution_m	metres	Spacing of the terrain and surface grid
device	"auto", "cuda", "cpu"	"auto" prefers CUDA and falls back to LLVM; "cuda" fails explicitly without a GPU

Geometry options identify the cached scene. Frequency, arrays, transmitters and solver settings remain ordinary Sionna state set after loading.

load_scene_async provides the same call for code that already runs inside an event loop, such as notebooks and services:

scene = await owrt.load_scene_async(latitude=52.3762, longitude=4.8993, radius_m=250)

Helpers that use the scene’s metadata

The loader registers the compiled directory with the returned scene. The following helpers accept either the scene object or a scene directory path:

Helper	Returns
owrt.scene_path(scene)	Directory that holds scene.xml, meshes and provenance
owrt.scene_frame(scene)	The LocalFrame WGS84 to ENU transform of the scene origin
owrt.position(scene, latitude=..., longitude=..., height_agl=...)	Absolute ENU position for a Sionna radio device
owrt.terrain_elevation(scene, east_m, north_m)	Local terrain elevation at an ENU position
owrt.measurement_surface(scene, cell_size=(10.0, 10.0), height=1.5)	Terrain-following Mitsuba mesh for RadioMapSolver
owrt.cache_path(latitude=..., longitude=..., radius_m=..., ...)	Cache directory a request would use, without compiling

Compiling without loading

compile_scene writes the same layout to an explicit output directory and returns the scene.xml path. It is asynchronous; compile_scene_sync wraps it for scripts and notebooks:

from openworld_radio_twin import compile_scene_sync

xml_path = compile_scene_sync(
    latitude=52.3762, longitude=4.8993, radius_m=250,
    output="scenes/amsterdam",
    receiver_height_m=1.5,
    receiver_cell_size=(10.0, 10.0),
    voxel_pitch_m=3.0,
    if_exists="reuse",            # "reuse" | "error" | "replace"
)

Unlike the cached loader, an explicit compilation also writes the receiver measurement surface and voxel products for the given receiver height, cell size and pitch. The command line exposes the same call:

owrt scene compile \
  --lat 52.3762 --lon 4.8993 --radius 250 \
  --output scenes/amsterdam \
  --buildings auto --building-source auto \
  --terrain elevation --material-profile itu --terrain-resolution 5 \
  --receiver-height 1.5 --receiver-cell-size 10 10 --voxel-pitch 3 \
  --if-exists reuse

The output is the layout described in Scene layout, identical to the per-scene directory of a generated dataset.

Scene cache

Geographic scenes compile into a directory named from the centre coordinates and a hash of every geometry-affecting input: the compiler version, the scene format and layout version, the building mesh schema, and the request itself. Two calls with the same options reuse one directory. A file lock serialises concurrent compilations of the same scene, and a scene is installed atomically, so an interrupted compilation never leaves a partially written cache.

The cache root is .cache/scenes under the checkout unless cache_dir or the OWRT_SCENE_CACHE_ROOT setting says otherwise. Delete a directory to force recompilation.

The web service uses the same cache. A scene compiled in the explorer or through POST /api/scenes is the directory owrt.load_scene would produce for the same inputs, and vice versa; the explorer reports such reuse as a cache hit.

Loading an existing scene directory

A compiled directory loads like any Sionna scene. Passing the directory to the helpers restores the frame and terrain without the original scene object:

scene = owrt.load_scene("scenes/amsterdam/scene.xml", device="cpu")
frame = owrt.scene_frame("scenes/amsterdam")

Because the XML and PLY files are plain Mitsuba assets, sionna.rt.load_scene also opens them; only the geographic helpers need OWRT.