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; with neither, the loader returns an empty scene as Sionna’s does.
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 |
|---|---|---|
|
|
Whether building geometry is retrieved at all |
|
|
Which provider supplies the buildings (Building sources) |
|
|
DEM-following ground, a planar ground, or no ground geometry (Terrain) |
|
|
Semantic surface classes with ITU proxies, or one material (Surfaces and materials) |
|
metres |
Spacing of the terrain and surface grid |
|
|
|
Geometry options identify the cached scene. Frequency, arrays, transmitters and solver settings remain ordinary Sionna state set after loading.
load_scene_async provides the geographic form 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. scene_path takes the
loaded scene and cache_path the geometry inputs; the other helpers accept the scene or a
scene directory path:
Helper |
Returns |
|---|---|
|
Directory that holds |
|
The |
|
Absolute ENU position for a Sionna radio device |
|
Local terrain elevation at an ENU position |
|
Terrain-following Mitsuba mesh for |
|
Antennas from a source that transmit on a downlink channel, placed for |
|
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 has the layout described in Scene layout, the same layout as 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, a geometry revision, the RF material profile version, and the request itself (Scene layout). 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")
The XML and PLY files are plain Mitsuba assets, so sionna.rt.load_scene also opens them
once openworld_radio_twin.simulation.water_material.register_water_material() has
registered the water material (Surfaces and materials). The geographic helpers need OWRT.