Scenes

sionna.rt.load_scene(filename=None, merge_shapes=True, merge_shapes_exclude_regex=None)[source]

Loads a scene from file

Parameters:

  • filename (typing.Optional[str]) – Name of a valid scene file. Sionna uses the simple XML-based format from Mitsuba 3. For None, an empty scene is created.

  • merge_shapes (bool) – If set to True, shapes that share the same radio material are merged.

  • merge_shapes_exclude_regex (typing.Optional[str]) – Optional regex to exclude shapes from merging. Only used if merge_shapes is set to True.

Return type:

sionna.rt.scene.Scene

class sionna.rt.Scene(mi_scene=None)[source]

A scene contains everything that is needed for radio propagation simulation and rendering.

A scene is a collection of multiple instances of SceneObject which define the geometry and materials of the objects in the scene. It also includes transmitters (Transmitter) and receivers (Receiver).

A scene is instantiated by calling load_scene().

Example scenes can be loaded as follows:

from sionna.rt import load_scene
scene = load_scene(sionna.rt.scene.munich)
scene.preview()
../../_images/scene_preview.png
Parameters:

mi_scene (typing.Optional[mitsuba.Scene]) – A Mitsuba scene

add(item)[source]

Adds a radio device or radio material to the scene

If a different item with the same name as item is part of the scene, an error is raised.

Parameters:

item (sionna.rt.radio_devices.radio_device.RadioDevice | sionna.rt.radio_materials.radio_material_base.RadioMaterialBase) – Item to be added to the scene

Return type:

None

all_set(radio_map)[source]

Raises an exception if the scene is not all set for simulations

Parameters:

radio_map (bool) – Set to True if checking for radio map computation. Set to False otherwise.

Return type:

None

property angular_frequency

Angular frequency [rad/s]

Type:

mi.Float

property bandwidth

Get/set the transmission bandwidth [Hz]. Used for the computation of thermal_noise_power.

Type:

mi.Float

edit(add=None, remove=None)[source]

Add and/or remove a list of objects to/from the scene

To optimize performance and reduce processing time, it is recommended to use a single call to this function with a list of objects to add and/or remove, rather than making multiple individual calls to edit scene objects.

Parameters:
Return type:

None

property frequency

Get/set the carrier frequency [Hz]

Type:

mi.Float

get(name)[source]

Returns a scene object, radio device, or radio material

Parameters:

name (str) – Name of the item to retrieve

Return type:

None | sionna.rt.radio_devices.radio_device.RadioDevice | sionna.rt.radio_materials.radio_material_base.RadioMaterialBase

property mi_scene

Mitsuba scene

Type:

mi.Scene

property mi_scene_params

Mitsuba scene parameters

Type:

mi.SceneParameters

property objects

Dictionary of scene objects

Type:

dict, { “name”, SceneObject}

property paths_solver

Get/set the path solver

Type:

rt.PathSolverBase

preview(*, background='white', clip_at=None, clip_plane_orientation=(0, 0, -1), fov=45.0, paths=None, radio_map=None, resolution=(655, 500), rm_db_scale=True, rm_metric='path_gain', rm_tx=None, rm_vmax=None, rm_vmin=None, show_devices=True, show_orientations=False)[source]

In an interactive notebook environment, opens an interactive 3D viewer of the scene.

Default color coding:

  • Green: Receiver

  • Blue: Transmitter

Controls:

  • Mouse left: Rotate

  • Scroll wheel: Zoom

  • Mouse right: Move

Parameters:

  • background (str) – Background color in hex format prefixed by “#”

  • clip_at (typing.Optional[float]) – If not None, the scene preview will be clipped (cut) by a plane with normal orientation clip_plane_orientation and offset clip_at. That means that everything behind the plane becomes invisible. This allows visualizing the interior of meshes, such as buildings.

  • clip_plane_orientation (tuple[float, float, float]) – Normal vector of the clipping plane

  • fov (float) – Field of view [deg]

  • paths (typing.Optional[sionna.rt.path_solvers.paths.Paths]) – Optional propagation paths to be shown

  • radio_map (typing.Optional[sionna.rt.radio_map_solvers.radio_map.RadioMap]) – Optional radio map to be shown

  • resolution (tuple[int, int]) – Size of the viewer figure

  • rm_db_scale (bool) – Use logarithmic scale for radio map visualization, i.e. the radio map values are mapped to: y=10⋅log10⁡(x).

  • rm_metric ("path_gain" | "rss" | "sinr") – Metric of the radio map to be displayed

  • rm_tx (typing.Union[int, str, None]) – When radio_map is specified, controls for which of the transmitters the radio map is shown. Either the transmitter’s name or index can be given. If None, the maximum metric over all transmitters is shown.

  • rm_vmax (typing.Optional[float]) – For radio map visualization, defines the maximum value that the colormap covers. It should be provided in dB if rm_db_scale is set to True, or in linear scale otherwise.

  • rm_vmin (typing.Optional[float]) – For radio map visualization, defines the minimum value that the colormap covers. It should be provided in dB if rm_db_scale is set to True, or in linear scale otherwise.

  • show_devices (bool) – Show radio devices

  • show_orientations (bool) – Show orientation of radio devices

Return type:

sionna.rt.preview.Previewer

property radio_materials

dict, { “name”, RadioMaterialBase}: Dictionary of radio materials

property receivers

Dictionary of receivers

Type:

dict, { “name”, Receiver}

remove(name)[source]

Removes a radio device or radio material from the scene

In the case of a radio material, it must not be used by any object of the scene.

Parameters:

name (str) – Name of the item to be removed

Return type:

None

render(*, camera, clip_at=None, clip_plane_orientation=(0, 0, -1), envmap=None, fov=45, lighting_scale=1.0, num_samples=128, paths=None, radio_map=None, resolution=(655, 500), return_bitmap=False, rm_db_scale=True, rm_metric='path_gain', rm_show_color_bar=False, rm_tx=None, rm_vmax=None, rm_vmin=None, show_devices=True)[source]

Renders the scene from the viewpoint of a camera or the interactive viewer

Parameters:

  • camera (sionna.rt.camera.Camera | str) – Camera to be used for rendering the scene. If an interactive viewer was opened with preview(), “preview” can be to used to render the scene from its viewpoint.

  • clip_at (typing.Optional[float]) – If not None, the scene preview will be clipped (cut) by a plane with normal orientation clip_plane_orientation and offset clip_at. That means that everything behind the plane becomes invisible. This allows visualizing the interior of meshes, such as buildings.

  • clip_plane_orientation (tuple[float, float, float]) – Normal vector of the clipping plane

  • envmap (typing.Optional[str]) – Path to an environment map image file (e.g. in EXR format) to use for scene lighting

  • fov (float) – Field of view [deg]

  • lighting_scale (float) – Scale to apply to the lighting in the scene (e.g., from a constant uniform emitter or a given environment map)

  • num_samples (int) – Number of rays thrown per pixel

  • paths (typing.Optional[sionna.rt.path_solvers.paths.Paths]) – Optional propagation paths to be shown

  • radio_map (typing.Optional[sionna.rt.radio_map_solvers.radio_map.RadioMap]) – Optional radio map to be shown

  • resolution (tuple[int, int]) – Size of the viewer figure

  • return_bitmap (bool) – If True, directly return the rendered image

  • rm_db_scale (bool) – Use logarithmic scale for radio map visualization, i.e. the radio map values are mapped to: y=10⋅log10⁡(x).

  • rm_metric ("path_gain" | "rss" | "sinr") – Metric of the radio map to be displayed

  • rm_show_color_bar (bool) – Show color bar

  • rm_tx (typing.Union[int, str, None]) – When radio_map is specified, controls for which of the transmitters the radio map is shown. Either the transmitter’s name or index can be given. If None, the maximum metric over all transmitters is shown.

  • rm_vmax (typing.Optional[float]) – For radio map visualization, defines the maximum value that the colormap covers. It should be provided in dB if rm_db_scale is set to True, or in linear scale otherwise.

  • rm_vmin (typing.Optional[float]) – For radio map visualization, defines the minimum value that the colormap covers. It should be provided in dB if rm_db_scale is set to True, or in linear scale otherwise.

  • show_devices (bool) – Show radio devices

Return type:

matplotlib.figure.Figure | mitsuba.Bitmap

render_to_file(*, camera, filename, clip_at=None, clip_plane_orientation=(0, 0, -1), envmap=None, fov=45, lighting_scale=1.0, num_samples=512, paths=None, radio_map=None, resolution=(655, 500), rm_db_scale=True, rm_metric='path_gain', rm_tx=None, rm_vmin=None, rm_vmax=None, show_devices=True)[source]

Renders the scene from the viewpoint of a camera or the interactive viewer, and saves the resulting image

Parameters:

  • camera (sionna.rt.camera.Camera | str) – Camera to be used for rendering the scene. If an interactive viewer was opened with preview(), “preview” can be to used to render the scene from its viewpoint.

  • filename (str) – Filename for saving the rendered image, e.g., “my_scene.png”

  • clip_at (typing.Optional[float]) – If not None, the scene preview will be clipped (cut) by a plane with normal orientation clip_plane_orientation and offset clip_at. That means that everything behind the plane becomes invisible. This allows visualizing the interior of meshes, such as buildings.

  • clip_plane_orientation (tuple[float, float, float]) – Normal vector of the clipping plane

  • envmap (typing.Optional[str]) – Path to an environment map image file (e.g. in EXR format) to use for scene lighting

  • fov (float) – Field of view [deg]

  • lighting_scale (float) – Scale to apply to the lighting in the scene (e.g., from a constant uniform emitter or a given environment map)

  • num_samples (int) – Number of rays thrown per pixel

  • paths (typing.Optional[sionna.rt.path_solvers.paths.Paths]) – Optional propagation paths to be shown

  • radio_map (typing.Optional[sionna.rt.radio_map_solvers.radio_map.RadioMap]) – Optional radio map to be shown

  • resolution (tuple[int, int]) – Size of the viewer figure

  • rm_db_scale (bool) – Use logarithmic scale for radio map visualization, i.e. the radio map values are mapped to: y=10⋅log10⁡(x).

  • rm_metric ("path_gain" | "rss" | "sinr") – Metric of the radio map to be displayed

  • rm_tx (typing.Union[int, str, None]) – When radio_map is specified, controls for which of the transmitters the radio map is shown. Either the transmitter’s name or index can be given. If None, the maximum metric over all transmitters is shown.

  • rm_vmax (typing.Optional[float]) – For radio map visualization, defines the maximum value that the colormap covers. It should be provided in dB if rm_db_scale is set to True, or in linear scale otherwise.

  • rm_vmin (typing.Optional[float]) – For radio map visualization, defines the minimum value that the colormap covers. It should be provided in dB if rm_db_scale is set to True, or in linear scale otherwise.

  • show_devices (bool) – Show radio devices

Return type:

mitsuba.Bitmap

property rx_array

Get/set the antenna array used by all receivers in the scene

Type:

AntennaArray

scene_geometry_updated()[source]

Callback to trigger when the scene geometry is updated

Return type:

None

sources(synthetic_array, return_velocities)[source]

Builds arrays containing the positions and orientations of the sources

If synthetic arrays are not used, then every transmit antenna is modeled as a source of paths. Otherwise, transmitters are modelled as if they had a single antenna located at their position.

Return type:

tuple[mitsuba.Point3f, mitsuba.Point3f, mitsuba.Point3f | None, mitsuba.Vector3f | None]

Returns:

Positions of the sources

Returns:

Orientations of the sources

Returns:

Positions of the antenna elements relative to the transmitters positions. None is returned if synthetic_array is True.

Returns:

Velocities of the transmitters. None is returned if return_velocities is set to False.

Parameters:

  • synthetic_array (bool)

  • return_velocities (bool)

targets(synthetic_array, return_velocities)[source]

Builds arrays containing the positions and orientations of the targets

If synthetic arrays are not used, then every receiver antenna is modeled as a source of paths. Otherwise, receivers are modelled as if they had a single antenna located at their position.

Return type:

tuple[mitsuba.Point3f, mitsuba.Point3f, mitsuba.Point3f | None, mitsuba.Vector3f | None]

Returns:

Positions of the targets

Returns:

Orientations of the targets

Returns:

Positions of the antenna elements relative to the receivers. Only returned if synthetic_array is True.

Returns:

Velocities of the transmitters. None is returned if return_velocities is set to False.

Parameters:

  • synthetic_array (bool)

  • return_velocities (bool)

property temperature

Get/set the environment temperature [K]. Used for the computation of thermal_noise_power.

Type:

mi.Float

property thermal_noise_power

Thermal noise power [W]

Type:

mi.Float

property transmitters

Dictionary of transmitters

Type:

dict, { “name”, Transmitter}

property tx_array

Get/set the antenna array used by all transmitters in the scene

Type:

AntennaArray

property wavelength

Wavelength [m]

Type:

mi.Float

Examples

Sionna has several integrated scenes that are listed below. They can be loaded and used as follows:

scene = load_scene(sionna.rt.scene.etoile)
scene.preview()
sionna.rt.scene.box

Example scene containing a metallic box

../../_images/box.png

(Blender file)

sionna.rt.scene.box_one_screen

Example scene containing a metallic box and a screen made of glass

Note: In the figure below, the upper face of the box has been removed for visualization purposes. In the actual scene, the box is closed on all sides.

../../_images/box_one_screen.png

(Blender file)

sionna.rt.scene.box_two_screens

Example scene containing a metallic box and two screens made of glass

Note: In the figure below, the upper face of the box has been removed for visualization purposes. In the actual scene, the box is closed on all sides.

../../_images/box_two_screens.png

(Blender file)

sionna.rt.scene.double_reflector

Example scene containing two metallic squares

../../_images/double_reflector.png

(Blender file)

sionna.rt.scene.etoile

Example scene containing the area around the Arc de Triomphe in Paris The scene was created with data downloaded from OpenStreetMap and the help of Blender and the Blender-OSM and Mitsuba Blender add-ons. The data is licensed under the Open Data Commons Open Database License (ODbL).

../../_images/etoile.png

(Blender file)

sionna.rt.scene.floor_wall

Example scene containing a ground plane and a vertical wall

../../_images/floor_wall.png

(Blender file)

sionna.rt.scene.florence

Example scene containing the area around the Florence Cathedral in Florence The scene was created with data downloaded from OpenStreetMap and the help of Blender and the Blender-OSM and Mitsuba Blender add-ons. The data is licensed under the Open Data Commons Open Database License (ODbL).

../../_images/florence.png

(Blender file)

sionna.rt.scene.munich

Example scene containing the area around the Frauenkirche in Munich The scene was created with data downloaded from OpenStreetMap and the help of Blender and the Blender-OSM and Mitsuba Blender add-ons. The data is licensed under the Open Data Commons Open Database License (ODbL).

../../_images/munich.png

(Blender file)

sionna.rt.scene.simple_reflector

Example scene containing a metallic reflector

../../_images/simple_reflector.png

(Blender file)

sionna.rt.scene.simple_street_canyon

Example scene containing a few rectangular building blocks and a ground plane

../../_images/street_canyon.png

(Blender file)

sionna.rt.scene.simple_street_canyon_with_cars

Example scene containing a few rectangular building blocks and a ground plane as well as some cars

../../_images/street_canyon_with_cars.png

(Blender file)

sionna.rt.scene.simple_wedge

Example scene containing a wedge with a 90∘ opening angle

../../_images/simple_wedge.png

(Blender file)

sionna.rt.scene.triple_reflector

Example scene containing three metallic rectangles

../../_images/triple_reflector.png

(Blender file)