Geographic scenes for Sionna RT#

This tutorial turns a WGS84 location into a native sionna.rt.Scene with buildings, terrain, and semantic ground surfaces (water, vegetation, pavement, bare ground), then runs a standard Sionna RT radio-map workflow on it. Compared with a regular Sionna notebook, only the scene-loading line changes. Antenna arrays, radio devices, RadioMapSolver, scene.preview(), and scene.render() are the unmodified upstream API.

Outline

  1. Setup

  2. Load a geographic scene

  3. Inspect the compiled geometry, materials, and provenance

  4. Preview the scene in interactive 3D

  5. Place a transmitter with geographic coordinates

  6. Compute a terrain-following radio map

  7. Preview the radio map in interactive 3D

  8. Analyse the radio map quantitatively

  9. Compare environments: materials, terrain, buildings

  10. Georeference the results

Requirements. Sionna RT 2.0.x with a working Mitsuba backend (CUDA or LLVM CPU) and the notebook extras:

pip install -e ".[rt,tutorial]"

The first run for a location downloads public building, terrain, and land-cover data and compiles a scene into a local cache; later runs reuse it. The parameters below use the finest values the dataset schema accepts: 1 m terrain mesh, 1 m receiver cells, 100 million rays per transmitter and depth 8; the viewer is 1920 x 1200. The whole notebook, including the four-environment comparison, takes about ten minutes on a multi-core CPU, most of it geometry compilation, and a minute or two on a GPU. All 3D views are Sionna’s live interactive viewer, so their output exists only while a kernel is running.

1. Setup#

Mitsuba’s execution variant is fixed per thread the first time it is selected. OWRT selects it from the device argument of load_scene, which is why sionna.rt is imported after the first load_scene call below. Everything else in this cell is an ordinary experiment definition.

import os
from pathlib import Path

import matplotlib.pyplot as plt
import numpy as np

from openworld_radio_twin import rt as owrt

DEVICE = "auto"  # "auto" | "cuda" | "cpu"
CACHE_DIR = Path(".cache/owrt-scenes")  # compiled scenes are reused across runs

# Amsterdam along the river Amstel: dense housing blocks, canals, and open water.
LOCATION = dict(latitude=52.3636, longitude=4.9019, radius_m=250)
TX_SITE = dict(latitude=52.3642, longitude=4.9030, height_agl=25.0)  # AGL: above ground level

FREQUENCY_HZ = 3.5e9
TX_POWER_DBM = 30.0
RX_HEIGHT_M = 1.5  # receiver height above the terrain
TERRAIN_RESOLUTION_M = 1.0  # terrain-mesh spacing
CELL_SIZE_M = 1.0  # receiver cell edge length
SAMPLES_PER_TX = 100_000_000
MAX_DEPTH = 8
SEED = 42

SCENE_VIEW = (1920, 1200)  # viewer size for the environment-only preview
RADIO_MAP_VIEW = (1920, 1080)  # a different size gives radio-map previews their own viewer

PATH_GAIN_LIMITS_DB = (-130.0, -70.0)  # one colour range for every path-gain figure

2. Load a geographic scene#

owrt.load_scene accepts everything sionna.rt.load_scene accepts. Passing latitude, longitude, and radius_m instead of a filename compiles the square region centred on that point:

Argument

Values

Effect

buildings

"auto", "none"

An automatic regional source where one covers the site (3DBAG here), else Overture Maps buildings with an OpenStreetMap fallback; or no buildings

terrain

"elevation", "flat", "none"

DEM-based terrain, a plane at z = 0, or no ground at all

material_profile

"itu", "uniform"

ITU-R P.2040 materials and the ITU-R P.527 water model per surface class, or concrete everywhere

terrain_resolution_m

metres

Terrain-mesh spacing and DEM sampling

device

"auto", "cuda", "cpu"

Mitsuba variant, selected before sionna.rt is imported

The compiled scene is a Sionna XML file plus PLY meshes in a deterministic cache directory; OWRT registers its water material before Sionna loads it. The returned object is a sionna.rt.Scene, not a wrapper.

scene = owrt.load_scene(
    **LOCATION,
    buildings="auto",
    terrain="elevation",
    material_profile="itu",
    terrain_resolution_m=TERRAIN_RESOLUTION_M,
    cache_dir=CACHE_DIR,
    device=DEVICE,
)

import sionna.rt as rt  # noqa: E402 - the Mitsuba variant is now fixed

print(type(scene))
print("Scene directory:", os.path.relpath(owrt.scene_path(scene)))
<class 'sionna.rt.scene.Scene'>
Scene directory: .cache/owrt-scenes/scene_p52.36360_p4.90190_40392d1f0e7993ef14d6

3. What was compiled#

With the itu profile, each surface class carries a documented ITU-R P.2040 surrogate: bare ground is medium dry ground, vegetation wood, and pavement concrete. Water follows the ITU-R P.527 water model instead: fresh water inland, sea water for water bodies that touch an ocean, sea, bay or strait. Terrain and water surfaces carry these materials as 10 m layers (terrain-*), so they reflect as half-spaces; building walls (itu_concrete) and roofs (itu_metal) keep Sionna’s default 0.1 m slab. Sionna merges shapes that share a material when it loads a scene, so the table below groups the scene by radio material. The river and the canals form the terrain-water object; building parts are merged into anonymous objects.

Everything here is a regular sionna.rt.SceneObject or RadioMaterial. Assigning a different RadioMaterial to scene.objects["terrain-water"].radio_material is the native way to test another water model.

ROLE = {
    "terrain-itu_medium_dry_ground": "exposed ground",
    "terrain-itu_wood": "vegetation",
    "terrain-itu_concrete": "paved ground",
    "terrain-p527_fresh_water": "inland water (river, canals)",
    "terrain-p527_sea_water": "sea water",
    "itu_concrete": "building walls",
    "itu_metal": "building roofs",
}

triangles = {}
for obj in scene.objects.values():
    material = obj.radio_material.name
    triangles[material] = triangles.get(material, 0) + obj.mi_mesh.face_count()

print(f"{'Radio material':<32}{'Role':<32}{'Triangles':>10}")
for material, count in sorted(triangles.items(), key=lambda item: -item[1]):
    print(f"{material:<32}{ROLE.get(material, ''):<32}{count:>10,}")
terrain_objects = sorted(name for name in scene.objects if name.startswith("terrain-"))
print(f"\nNamed terrain objects: {terrain_objects}")
Radio material                  Role                             Triangles
terrain-itu_medium_dry_ground   exposed ground                     293,660
terrain-p527_fresh_water        inland water (river, canals)       142,976
terrain-itu_concrete            paved ground                        62,798
itu_concrete                    building walls                      36,584
itu_metal                       building roofs                      16,770
terrain-itu_wood                vegetation                             566

Named terrain objects: ['terrain-ground', 'terrain-paved', 'terrain-vegetation', 'terrain-water']

Every compiled scene carries its data provenance. The summary below is read from the scene directory; the ENU coordinate contract and the compilation record are in provenance.json, and the sources’ releases, licences and credits are in source_buildings.json and terrain/scene_info.json.

import json

scene_dir = owrt.scene_path(scene)
compilation = json.loads((scene_dir / "scene_info.json").read_text())["provenance"]
terrain_info = json.loads((scene_dir / "terrain" / "scene_info.json").read_text())

release = compilation["building_release"]
print(
    f"Buildings : {compilation['exported_building_count']} from {compilation['building_provider']}"
    f"{f' {release}' if release else ''} "
    f"({compilation['boundary_excluded_building_count']} crossing the scene boundary were excluded)"
)
print(
    f"Terrain   : {terrain_info['terrain_source']['provider']}, "
    f"{terrain_info['terrain_source']['source_resolution_m']:.0f} m source resolution"
)
surface_source = terrain_info["surface_source"]
print(f"Surfaces  : {surface_source['provider']} {surface_source['release']}")
print("Warnings  :")
for warning in compilation["warnings"]:
    print("  -", warning)
Buildings : 611 from 3DBAG (85 crossing the scene boundary were excluded)
Terrain   : Mapzen Terrain Tiles, 31 m source resolution
Surfaces  : Overture Maps 2026-09-23.1
Warnings  :
  - Skipped 3DBAG feature NL.IMBAG.Pand.0363100012171837: CityJSON face exceeds planarity tolerance
  - Omitted 6 collinear zero-area source faces; all nondegenerate source faces of those parts were retained.
  - Excluded 85 building footprints crossing the square scene boundary.
  - Global terrain uses a multi-source Mapzen mosaic; regional source accuracy, datum consistency, and attribution must be reviewed in exported metadata.
  - 100 road sections lacked source width; deterministic class widths are recorded as assumptions.
  - 25 road sections lacked source surface; deterministic road-class surfaces are recorded as assumptions.

4. Preview the scene in interactive 3D#

scene.preview() is Sionna’s interactive viewer, built on ipywidgets and pythreejs. It shows the complete compiled geometry at full resolution: drag to orbit, scroll to zoom, right-drag to pan, and Alt+click to read a point’s coordinates. Water is drawn in blue, vegetation in green, bare ground in brown, and buildings in grey. This first view contains no radio map; it is the place to check the river, the canals, the terrain, and the buildings before any transmitter is added.

JupyterLab renders the widget out of the box. VS Code has to be allowed to fetch the widget’s JavaScript: add the following to your settings, reload the window, and restart the kernel.

"jupyter.widgetScriptSources": ["jsdelivr.com", "unpkg.com"]

The widget lives in the running kernel and is not stored in the committed notebook. For a paper figure, scene.render_to_file(camera="preview", filename=...) traces the current viewer pose with Mitsuba’s path tracer.

Sionna keeps one cached viewer per scene and redraws it in place on every preview() call, so a later call with a radio map would also change this output. Requesting a different resolution makes Sionna create an independent viewer; that is why the radio-map previews below use RADIO_MAP_VIEW while this one uses SCENE_VIEW.

scene.preview(resolution=SCENE_VIEW)

5. Place a transmitter with geographic coordinates#

Sionna positions radio devices in metres in the scene frame. OWRT’s frame is topocentric east-north-up at the scene centre, with z = 0 at the modelled terrain elevation of that centre. owrt.position converts latitude, longitude, and a height above ground level into that frame, terrain included. The device itself is a standard sionna.rt.Transmitter; any Sionna antenna array works.

scene.frequency = FREQUENCY_HZ
scene.tx_array = rt.PlanarArray(num_rows=1, num_cols=1, pattern="iso", polarization="V")
scene.rx_array = rt.PlanarArray(num_rows=1, num_cols=1, pattern="iso", polarization="V")

tx_position = owrt.position(scene, **TX_SITE)
scene.add(rt.Transmitter(name="tx", position=tx_position, power_dbm=TX_POWER_DBM))

east, north, z = tx_position
print(f"Transmitter in scene coordinates: east {east:.1f} m, north {north:.1f} m, z {z:.2f} m")
print(
    f"Terrain under the transmitter: {owrt.terrain_elevation(scene, east, north):.2f} m, "
    f"antenna {TX_SITE['height_agl']:.1f} m above it"
)
Transmitter in scene coordinates: east 74.9 m, north 66.8 m, z 26.61 m
Terrain under the transmitter: 1.61 m, antenna 25.0 m above it

6. Compute a terrain-following radio map#

Sionna’s default radio-map surface is a horizontal plane. Over real terrain the receivers should follow the ground, which Sionna supports through the measurement_surface argument of RadioMapSolver (see Radio Maps in the Sionna documentation). owrt.measurement_surface builds that mesh: a regular grid whose every vertex sits height metres above the local terrain, two triangles per cell. The solver call is unchanged Sionna.

measurement_surface = owrt.measurement_surface(scene, cell_size=CELL_SIZE_M, height=RX_HEIGHT_M)
print(
    f"Measurement surface: {measurement_surface.face_count():,} triangles, "
    f"two per {CELL_SIZE_M:g} m x {CELL_SIZE_M:g} m cell, {RX_HEIGHT_M} m above the terrain"
)

solver = rt.RadioMapSolver()
radio_map = solver(
    scene,
    measurement_surface=measurement_surface,
    samples_per_tx=SAMPLES_PER_TX,
    max_depth=MAX_DEPTH,
    seed=SEED,
)
print(f"{type(radio_map).__name__} with {radio_map.cells_count:,} cells")
Measurement surface: 500,000 triangles, two per 1 m x 1 m cell, 1.5 m above the terrain
MeshRadioMap with 500,000 cells

7. Preview the radio map in interactive 3D#

The same viewer accepts the radio map and drapes it over the terrain-following measurement surface, one colour per triangle, two per 1 m cell. rm_metric selects "path_gain", "rss", or "sinr", and fixed rm_vmin/rm_vmax keep the colour scale identical across figures. This notebook displays path gain, which does not depend on the transmit power; with a single transmitter, RSS in dBm is path gain plus the transmit power.

If you also call scene.render(radio_map=..., rm_metric="rss"): in Sionna RT 2.0.1 it can scale the radio map in place by a factor of 1000 when a transmitter radiates exactly 1 W (30 dBm), because the dBm conversion is applied to a zero-copy view of the path-gain tensor. Rendering "path_gain" avoids this.

scene.preview(
    radio_map=radio_map,
    rm_metric="path_gain",
    rm_vmin=PATH_GAIN_LIMITS_DB[0],
    rm_vmax=PATH_GAIN_LIMITS_DB[1],
    resolution=RADIO_MAP_VIEW,
)

8. Analyse the radio map quantitatively#

radio_map.cdf() is native. For a top-down map, Sionna provides show() only for planar radio maps; a mesh radio map holds one value per triangle, so it is plotted with Matplotlib’s tripcolor straight from radio_map.measurement_surface. The two helpers below work for any MeshRadioMap, not only for OWRT scenes.

radio_map.cdf(metric="path_gain");
../_images/087f70c1f0d9e8d288195ed164f1291ce7d3a6f7696a505f8f84e20da1637056.png
def metric_db(radio_map, metric="path_gain"):
    """Strongest-transmitter value per triangle in dB (dBm for RSS); NaN where no path arrived."""
    linear = radio_map.transmitter_radio_map(metric).numpy()
    offset = 30.0 if metric == "rss" else 0.0
    with np.errstate(divide="ignore"):
        return np.where(linear > 0, 10.0 * np.log10(linear) + offset, np.nan)


def show_mesh_radio_map(
    scene,
    radio_map,
    values_db,
    *,
    ax=None,
    label="Path gain (dB)",
    cmap="viridis",
    vmin=None,
    vmax=None,
):
    """Plot one value per measurement-surface triangle; grey marks missing coverage."""
    mesh = radio_map.measurement_surface
    vertices = np.asarray(mesh.vertex_positions_buffer()).reshape(-1, 3)
    faces = np.asarray(mesh.faces_buffer()).reshape(-1, 3)
    if ax is None:
        _, ax = plt.subplots(figsize=(6.4, 5.6), constrained_layout=True)
    ax.set_facecolor("#e6e8eb")
    image = ax.tripcolor(
        vertices[:, 0], vertices[:, 1], faces, facecolors=values_db, cmap=cmap, vmin=vmin, vmax=vmax
    )
    for tx in scene.transmitters.values():
        x, y, _ = tx.position.numpy().ravel()
        ax.plot(x, y, "^", color="crimson", markersize=9, markeredgecolor="white")
    ax.set_aspect("equal")
    ax.set_xlabel("East (m)")
    ax.set_ylabel("North (m)")
    ax.figure.colorbar(image, ax=ax, label=label, shrink=0.85)
    return ax
path_gain_db = metric_db(radio_map)

ax = show_mesh_radio_map(
    scene, radio_map, path_gain_db, vmin=PATH_GAIN_LIMITS_DB[0], vmax=PATH_GAIN_LIMITS_DB[1]
)
ax.set_title(f"Path gain at {RX_HEIGHT_M} m above ground, {CELL_SIZE_M:g} m cells")

covered = np.isfinite(path_gain_db)
print(f"Covered cells: {covered.mean():.1%}")
print(f"Median path gain over covered cells: {np.nanmedian(path_gain_db):.1f} dB")
Covered cells: 73.6%
Median path gain over covered cells: -96.8 dB
../_images/6746235c98c827aa69571907ee1bf0d04dd6dd220cdd43da67caadbc8afcba2e.png

9. Compare environments: materials, terrain, buildings#

Because the environment is described by keyword arguments, an ablation is a second load_scene call with one argument changed. The transmitter, arrays, solver settings, and receiver grid stay identical, and every variant’s measurement grid has the same triangle order, so per-cell differences are well defined. Each variant is its own Scene, so each one also gets its own interactive viewer.

Scenario

Change

Isolates

ITU materials

none (the scene above)

reference

Uniform concrete

material_profile="uniform"

semantic materials: water, vegetation, ground

Flat terrain

terrain="flat"

terrain relief

No buildings

buildings="none"

building geometry

def solve_variant(**scene_options):
    """Load a variant of LOCATION and solve it with the radio configuration used above."""
    variant = owrt.load_scene(
        **LOCATION,
        terrain_resolution_m=TERRAIN_RESOLUTION_M,
        cache_dir=CACHE_DIR,
        device=DEVICE,
        **scene_options,
    )
    variant.frequency = FREQUENCY_HZ
    variant.tx_array = rt.PlanarArray(num_rows=1, num_cols=1, pattern="iso", polarization="V")
    variant.rx_array = rt.PlanarArray(num_rows=1, num_cols=1, pattern="iso", polarization="V")
    variant.add(
        rt.Transmitter(
            name="tx", position=owrt.position(variant, **TX_SITE), power_dbm=TX_POWER_DBM
        )
    )
    surface = owrt.measurement_surface(variant, cell_size=CELL_SIZE_M, height=RX_HEIGHT_M)
    variant_map = solver(
        variant,
        measurement_surface=surface,
        samples_per_tx=SAMPLES_PER_TX,
        max_depth=MAX_DEPTH,
        seed=SEED,
    )
    return variant, variant_map


SCENARIOS = {
    "ITU materials": {},
    "Uniform concrete": dict(material_profile="uniform"),
    "Flat terrain": dict(terrain="flat"),
    "No buildings": dict(buildings="none"),
}

results = {"ITU materials": (scene, radio_map)}
for name, options in SCENARIOS.items():
    if name not in results:
        results[name] = solve_variant(**options)
maps_db = {name: metric_db(variant_map) for name, (_, variant_map) in results.items()}

One interactive viewer per scenario, all on the same colour scale. Orbit each one to compare how the river, the terrain, and the buildings shape the coverage.

for name, (variant, variant_map) in results.items():
    print(name)
    variant.preview(
        radio_map=variant_map,
        rm_metric="path_gain",
        rm_vmin=PATH_GAIN_LIMITS_DB[0],
        rm_vmax=PATH_GAIN_LIMITS_DB[1],
        resolution=RADIO_MAP_VIEW,
    )
ITU materials
Uniform concrete
Flat terrain
No buildings

The quantitative view: top row, path gain per scenario on a shared scale; bottom row, the distribution over covered cells and each variant’s per-cell difference to the reference.

reference_db = maps_db["ITU materials"]
fig, axes = plt.subplots(2, len(maps_db), figsize=(5.4 * len(maps_db), 10), constrained_layout=True)

for column, (name, values_db) in enumerate(maps_db.items()):
    variant, variant_map = results[name]
    show_mesh_radio_map(
        variant,
        variant_map,
        values_db,
        ax=axes[0, column],
        vmin=PATH_GAIN_LIMITS_DB[0],
        vmax=PATH_GAIN_LIMITS_DB[1],
    )
    axes[0, column].set_title(name)
    if column == 0:
        continue
    delta_db = values_db - reference_db
    limit = float(np.nanpercentile(np.abs(delta_db), 98))
    show_mesh_radio_map(
        variant,
        variant_map,
        delta_db,
        ax=axes[1, column],
        cmap="RdBu_r",
        vmin=-limit,
        vmax=limit,
        label="Difference to reference (dB)",
    )
    axes[1, column].set_title(f"{name} minus ITU materials")

for name, values_db in maps_db.items():
    covered_db = np.sort(values_db[np.isfinite(values_db)])
    axes[1, 0].plot(covered_db, np.linspace(0, 1, covered_db.size), label=name)
axes[1, 0].set(xlabel="Path gain (dB)", ylabel="CDF over covered cells", title="Distribution")
axes[1, 0].grid(alpha=0.3)
axes[1, 0].legend()

print(f"{'Scenario':<18}{'Covered':>9}{'Median (dB)':>13}{'Median |diff|':>15}{'95% |diff|':>12}")
for name, values_db in maps_db.items():
    delta_db = np.abs(values_db - reference_db)
    diff = (
        "reference".rjust(27)
        if name == "ITU materials"
        else (f"{np.nanmedian(delta_db):>15.2f}{np.nanpercentile(delta_db, 95):>12.2f}")
    )
    print(f"{name:<18}{np.isfinite(values_db).mean():>8.1%}{np.nanmedian(values_db):>13.1f}{diff}")
Scenario            Covered  Median (dB)  Median |diff|  95% |diff|
ITU materials        73.6%        -96.8                  reference
Uniform concrete     77.0%        -97.8           0.71       15.10
Flat terrain         73.3%        -97.5           1.06       21.18
No buildings         96.7%        -88.9           9.25       51.75
../_images/b8ef1c9113ca3c586a55611787c1a596369b463c98ad04bff4b6c227a47f2d3f.png

These statistics describe one ray-tracing run per scenario at 100 million rays per transmitter; repeating each scenario with several seeds measures their spread.

10. Georeference the results#

Everything so far is in scene metres. owrt.scene_frame returns the WGS84-to-ENU transform of the scene, so any cell centre or device position converts back to latitude and longitude. The measurement grid also has a fixed layout, documented in the JSON file next to the mesh: triangles 2k and 2k+1 belong to cell k = row * columns + column, with rows running south to north and columns west to east. A mesh radio map therefore reshapes into a raster without a lookup table.

import math

frame = owrt.scene_frame(scene)
centers = radio_map.cell_centers
strongest = int(np.nanargmax(path_gain_db))
longitude, latitude, _ = frame.to_geographic(
    float(centers.x.numpy()[strongest]), float(centers.y.numpy()[strongest])
)
print(f"Strongest cell: {latitude:.6f} N, {longitude:.6f} E, {path_gain_db[strongest]:.1f} dB")

columns = rows = math.ceil(2 * LOCATION["radius_m"] / CELL_SIZE_M)
cell_linear = (
    radio_map.transmitter_radio_map("path_gain").numpy().reshape(rows, columns, 2).mean(axis=-1)
)
with np.errstate(divide="ignore"):
    raster_db = np.where(cell_linear > 0, 10.0 * np.log10(cell_linear), np.nan)
print(f"Raster: {raster_db.shape} cells; row 0 is the south edge, column 0 the west edge")

west, south = frame.to_geographic(-LOCATION["radius_m"], -LOCATION["radius_m"])[:2]
east_, north_ = frame.to_geographic(LOCATION["radius_m"], LOCATION["radius_m"])[:2]
print(f"Raster bounds: {south:.6f} N to {north_:.6f} N, {west:.6f} E to {east_:.6f} E")
Strongest cell: 52.364160 N, 4.902776 E, -68.3 dB
Raster: (500, 500) cells; row 0 is the south edge, column 0 the west edge
Raster bounds: 52.361353 N to 52.365847 N, 4.898230 E to 4.905570 E

Reproducibility notes#

  • Cache. Scenes are keyed by the software version; the scene layout, building mesh schema, geometry revision and RF material profile versions; the geometry arguments (latitude, longitude, radius_m, buildings, building_source, terrain, material_profile, terrain_resolution_m); and the resolved building source with its version. Frequency, arrays, transmitters, receiver grids, and solver settings never trigger a recompile. The cache root is cache_dir, else OWRT_SCENE_CACHE_ROOT, else .cache/scenes under the checkout.

  • Offline use. owrt scene compile --lat 52.3636 --lon 4.9019 --radius 250 --output scenes/amstel writes the same directory layout. Passing the directory to owrt.load_scene loads it with the geographic helpers available. Its scene.xml also loads with plain sionna.rt.load_scene once register_water_material() from openworld_radio_twin.simulation.water_material has registered the water material.

  • Provenance. provenance.json records the coordinate contract, the material profile, and the building provider and release. source_buildings.json and terrain/scene_info.json record the sources’ releases, licences and credits; cite those sources together with Sionna RT.

  • Fidelity. The notebook already runs at 1 m terrain and receiver resolution with 100 million rays per transmitter. The terrain source itself is coarser (about 31 m for this location), so the 1 m mesh oversamples it; buildings and the semantic surfaces are the parts that benefit. Raise LOCATION["radius_m"] for a larger district and use a GPU (device="cuda") to keep the turnaround short. Sionna’s own tutorials on paths, multi-transmitter coverage, and differentiable ray tracing apply to these scenes without modification.