openworld_radio_twin.models#

Classes

AntennaDefaults(**data)

Values placement uses where a source gives none.

AntennaFeature(**data)

One radiating antenna as a source records it; one Sionna Transmitter once placed.

AntennaOperator(**data)

An operator present in a scene; id is the value the operator filter takes.

AntennaRequest(**data)

Antennas from one source inside a compiled scene, or inside a square on the map.

AntennaResponse(**data)

Selected antennas, with the operators, radios and channels present before selection.

BuildingContextResponse(**data)

BuildingFeature(**data)

BuildingGeometry(**data)

Source-resolved triangle shell, before scene placement.

BuildingGeometryContext(**data)

Solver-coordinate native shells, with no visual offset or vertical scaling.

Channel(**data)

A downlink or TDD range an antenna of the scene registers.

ChannelRange(**data)

A downlink channel to simulate: centre_hz is Sionna's scene.frequency and bandwidth_hz its scene.bandwidth.

Coordinate(**data)

CoverageGrid(**data)

Emission(**data)

One distinct range an antenna registers, with its link direction.

EngineName(value)

EnvironmentContext(**data)

FrequencyBand(**data)

One registered frequency range with the source's system label, e.g. "LTE 1800".

FrequencyRange(**data)

A frequency range in MHz, kept to 1 kHz.

GridMapping(**data)

NativeBuildingMesh(**data)

RadioLayer(**data)

SceneBounds(**data)

SceneCenter(**data)

Explicit scene origin; the compiled square is centred here rather than on the first TX.

SceneRequest(**data)

Geometry inputs of a compiled scene, keyed like openworld_radio_twin.rt.load_scene.

SceneResponse(**data)

A compiled, cached scene as the browser displays it.

SearchResult(**data)

SimulationRequest(**data)

SimulationResponse(**data)

SionnaEngineConfig(**data)

Runtime and geometry controls for the built-in Sionna RT adapter.

SurfaceContext(**data)

TerrainContext(**data)

TransmitterConfig(**data)

TransmitterSource(**data)

The antenna record a transmitter was taken from, and where each value came from.

class openworld_radio_twin.models.EngineName(value)[source]#

Bases: str, Enum

preview = 'preview'#
sionna = 'sionna'#
class openworld_radio_twin.models.Coordinate(**data)[source]#

Bases: BaseModel

latitude: float#
longitude: float#
altitude_m: float#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.TransmitterSource(**data)[source]#

Bases: BaseModel

The antenna record a transmitter was taken from, and where each value came from.

feature_id: str#
source: str#
release: str | None#
basis: dict[str, Literal['source', 'derived', 'default', 'adjusted', 'user']]#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.TransmitterConfig(**data)[source]#

Bases: BaseModel

position: Coordinate#
frequency_ghz: float#
power_dbm: float#
azimuth_deg: float#
downtilt_deg: float#
antenna_pattern: str#
source: TransmitterSource | None#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.SionnaEngineConfig(**data)[source]#

Bases: BaseModel

Runtime and geometry controls for the built-in Sionna RT adapter.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

device: Literal['auto', 'cuda', 'cpu']#
include_ground: bool#
include_vegetation: bool#
include_paved: bool#
include_water: bool#
include_building_roofs: bool#
include_building_walls: bool#
los: bool#
specular_reflection: bool#
diffuse_reflection: bool#
refraction: bool#
diffraction: bool#
edge_diffraction: bool#
diffraction_lit_region: bool#
class openworld_radio_twin.models.SceneRequest(**data)[source]#

Bases: BaseModel

Geometry inputs of a compiled scene, keyed like openworld_radio_twin.rt.load_scene.

latitude: float#
longitude: float#
radius_m: float#
include_buildings: bool#
building_source: str#
include_terrain: bool#
material_profile: Literal['itu', 'uniform']#
terrain_resolution_m: float#
limit_terrain_grid()[source]#
Return type:

SceneRequest

property buildings_mode: Literal['auto', 'none']#
property terrain_mode: Literal['elevation', 'flat']#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.SceneCenter(**data)[source]#

Bases: BaseModel

Explicit scene origin; the compiled square is centred here rather than on the first TX.

latitude: float#
longitude: float#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.SimulationRequest(**data)[source]#

Bases: BaseModel

transmitters: list[TransmitterConfig]#
scene_center: SceneCenter | None#
engine: str#
engine_config: dict[str, str | int | float | bool]#
radius_m: float#
resolution_m: float#
receiver_height_m: float#
max_depth: int#
samples_per_tx: int#
seed: int#
association_metric: str#
bandwidth_mhz: float#
include_buildings: bool#
building_source: str#
include_terrain: bool#
material_profile: Literal['itu', 'uniform']#
terrain_resolution_m: float#
limit_grid_size()[source]#
Return type:

SimulationRequest

property include_surface_materials: bool#

Return whether semantic surface classes are required by this request.

Classes are assigned on the ground grid whether that grid follows the DEM or is a flat plane; only the uniform profile omits them.

property include_environment_grid: bool#

Return whether a gridded ground (DEM or flat) must be acquired for this request.

The planar preview engine ignores materials, so a flat scene only needs the environment grid when Sionna evaluates it.

property reference_transmitter: TransmitterConfig#

First TX; it sets the shared antenna preset and, without scene_center, the origin.

property scene_origin: SceneCenter#

Local ENU origin and coverage-grid centre of the compiled scene.

property scene_request: SceneRequest#

Geometry of the compiled scene this simulation runs in.

model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.BuildingGeometry(**data)[source]#

Bases: BaseModel

Source-resolved triangle shell, before scene placement.

Horizontal coordinates use crs; vertex Z and ground_elevation_m use the explicitly named vertical datum, never implicit WGS84 heights.

crs: str#
vertical_datum: str#
lod: str#
ground_elevation_m: float#
vertices: list[tuple[float, float, float]]#
triangles: list[tuple[int, int, int]]#
surface_types: list[str]#
validate_mesh()[source]#
Return type:

BuildingGeometry

model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.BuildingFeature(**data)[source]#

Bases: BaseModel

feature_id: str#
source: str#
feature_type: str#
source_dataset_id: str | None#
parent_building_id: str | None#
source_record_id: str | None#
source_release: str | None#
name: str | None#
height_m: float#
min_height_m: float#
height_source: str#
height_uncertainty_m: float | None#
coordinates: list[list[float]]#
holes: list[list[list[float]]]#
geometry: BuildingGeometry | None#
source_attributes: dict[str, object]#
property roof_height_agl_m: float#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.FrequencyRange(**data)[source]#

Bases: BaseModel

A frequency range in MHz, kept to 1 kHz.

low_mhz: float#
high_mhz: float#
classmethod to_kilohertz(value)[source]#
Return type:

float

ordered()[source]#
Return type:

FrequencyRange

property width_mhz: float#
property centre_hz: float#

The centre frequency in Hz, the value of Sionna’s scene.frequency.

property bandwidth_hz: float#

The width in Hz, the value of Sionna’s scene.bandwidth.

contains(other)[source]#
Return type:

bool

covers(frequency_hz)[source]#
Return type:

bool

model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.FrequencyBand(**data)[source]#

Bases: FrequencyRange

One registered frequency range with the source’s system label, e.g. “LTE 1800”.

link is set when the source itself states the direction, as a register of transmitters does; otherwise the 3GPP bands classify the range.

label: str#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.Emission(**data)[source]#

Bases: FrequencyRange

One distinct range an antenna registers, with its link direction.

Systems registered on the same range, such as LTE and NR sharing a block, form one emission. link comes from the 3GPP operating bands, see openworld_radio_twin.spectrum.

labels: list[str]#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.ChannelRange(**data)[source]#

Bases: FrequencyRange

A downlink channel to simulate: centre_hz is Sionna’s scene.frequency and bandwidth_hz its scene.bandwidth.

usable_width()[source]#
Return type:

ChannelRange

model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.Channel(**data)[source]#

Bases: ChannelRange

A downlink or TDD range an antenna of the scene registers.

antenna_count, operators and labels describe the antennas that transmit on it: those registering a downlink or TDD range that contains it. A channel of network sharing lists both operators. sionna_supported tells whether its centre lies inside SIONNA_FREQUENCY_RANGE_GHZ.

labels: list[str]#
operators: list[str]#
antenna_count: int#
sionna_supported: bool#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.AntennaFeature(**data)[source]#

Bases: BaseModel

One radiating antenna as a source records it; one Sionna Transmitter once placed.

A value the source does not give stays None until placement fills it from AntennaDefaults. basis names where each value came from: source, derived (computed from source data, such as a centroid), default or adjusted (moved by a placement rule). position and orientation are the Sionna scene coordinates and rotation angles, set by placement in a compiled scene.

feature_id: str#
source: str#
source_release: str | None#
site_id: str#
operator: str | None#
plmn: str | None#
radios: list[Literal['GSM', 'UMTS', 'LTE', 'NR', 'NBIOT', 'CDMA']]#
bands: list[FrequencyBand]#
latitude: float#
longitude: float#
height_agl_m: float | None#
azimuth_deg: float | None#
downtilt_deg: float | None#
power_dbm: float | None#
basis: dict[str, Literal['source', 'derived', 'default', 'adjusted', 'user']]#
position: tuple[float, float, float] | None#
orientation: tuple[float, float, float] | None#
source_attributes: dict[str, object]#
property operator_id: str#

the PLMN, else the operator name.

Type:

The value the operator selection matches

property emissions: list[Emission]#

The antenna’s distinct registered ranges, each with its link direction.

transmits_on(channel)[source]#

Whether a downlink or TDD range the antenna registers contains channel.

Return type:

bool

model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.AntennaDefaults(**data)[source]#

Bases: BaseModel

Values placement uses where a source gives none.

Where Sionna RT defines a default, it is used: 44 dBm transmit power (sionna.rt.constants.DEFAULT_TRANSMIT_POWER_DBM) and the zero orientation, whose boresight points east (compass azimuth 90 degrees) and is horizontal (no downtilt). Sionna has no default height; 25 m above ground is the existing OWRT transmitter default. sectors expands a site without a direction into one antenna per azimuth, and roof_clearance_m is how far above a roof an antenna inside a building is raised.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

height_agl_m: float#
azimuth_deg: float#
downtilt_deg: float#
power_dbm: float#
sectors: tuple[float, ...] | None#
roof_clearance_m: float#
valid_sectors()[source]#
Return type:

AntennaDefaults

class openworld_radio_twin.models.GridMapping(**data)[source]#

Bases: BaseModel

horizontal_datum: str#
local_axes: str#
origin_longitude: float#
origin_latitude: float#
first_sample_east_m: float#
first_sample_north_m: float#
column_step_m: float#
row_step_m: float#
sample_layout: str#
corner_coordinates: list[list[float]]#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.RadioLayer(**data)[source]#

Bases: BaseModel

label: str#
unit: str#
values: list[float | None] | None#
minimum: float#
maximum: float#
display_minimum: float#
display_maximum: float#
reduction: str#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.CoverageGrid(**data)[source]#

Bases: BaseModel

crs: str#
no_data_value: None#
receiver_height_agl_m: float#
grid_mapping: GridMapping#
west: float#
south: float#
east: float#
north: float#
width: int#
height: int#
layers: dict[str, RadioLayer]#
association: list[int] | None#
building_mask: list[bool] | None#
building_heights_m: list[float | None] | None#
building_cell_count: int#
validate_aligned_grids()[source]#
Return type:

CoverageGrid

model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.NativeBuildingMesh(**data)[source]#

Bases: BaseModel

feature_id: str#
vertices: list[tuple[float, float, float]]#
triangles: list[tuple[int, int, int]]#
surface_types: list[str]#
lod: str#
placement_rule: str#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.BuildingGeometryContext(**data)[source]#

Bases: BaseModel

Solver-coordinate native shells, with no visual offset or vertical scaling.

origin_longitude: float#
origin_latitude: float#
coordinate_system: str#
meshes: list[NativeBuildingMesh]#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.SimulationResponse(**data)[source]#

Bases: BaseModel

simulation_id: str#
engine: str#
elapsed_ms: int#
coverage: CoverageGrid#
buildings: list[BuildingFeature]#
building_geometry: BuildingGeometryContext | None#
warnings: list[str]#
engine_details: dict[str, str | int | float | bool]#
data_provenance: dict[str, str | int | float | bool]#
environment: EnvironmentContext | None#
scene: SceneResponse | None#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.SceneBounds(**data)[source]#

Bases: BaseModel

origin_longitude: float#
origin_latitude: float#
radius_m: float#
wgs84_corners: list[list[float]]#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.SceneResponse(**data)[source]#

Bases: BaseModel

A compiled, cached scene as the browser displays it.

scene_id is the cache directory name shared with openworld_radio_twin.rt.load_scene for the same geometry inputs; the buildings and environment are read from that directory.

scene_id: str#
cached: bool#
specification: SceneRequest#
bounds: SceneBounds#
buildings: list[BuildingFeature]#
building_geometry: BuildingGeometryContext | None#
environment: EnvironmentContext | None#
warnings: list[str]#
data_provenance: dict[str, str | int | float | bool]#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.TerrainContext(**data)[source]#

Bases: BaseModel

width: int#
height: int#
east_m: list[float]#
north_m: list[float]#
local_elevation_m: list[float]#
origin_elevation_m: float#
minimum_local_elevation_m: float#
maximum_local_elevation_m: float#
model_operations: list[dict[str, object]]#
source: dict[str, object]#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.SurfaceContext(**data)[source]#

Bases: BaseModel

width: int#
height: int#
classes: list[int]#
legend: dict[int, str]#
material_profile_version: int#
material_profiles: dict[str, dict[str, str]]#
provenance: dict[str, object]#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.EnvironmentContext(**data)[source]#

Bases: BaseModel

terrain: TerrainContext#
surfaces: SurfaceContext#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.BuildingContextResponse(**data)[source]#

Bases: BaseModel

buildings: list[BuildingFeature]#
building_geometry: BuildingGeometryContext | None#
warnings: list[str]#
data_provenance: dict[str, str | int | float | bool]#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.AntennaOperator(**data)[source]#

Bases: BaseModel

An operator present in a scene; id is the value the operator filter takes.

id: str#
name: str#
count: int#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.AntennaRequest(**data)[source]#

Bases: BaseModel

Antennas from one source inside a compiled scene, or inside a square on the map.

With scene_id the antennas are placed in that scene as Sionna transmitters. With latitude, longitude and radius_m instead, they are completed with defaults but not placed, for viewing before a scene is compiled. channel keeps the antennas that transmit on it; an antenna that registers no frequencies, as with OpenCelliD, is assumed to and counted in a warning.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

scene_id: str | None#
latitude: float | None#
longitude: float | None#
radius_m: float | None#
antenna_source: str#
operator: str | None#
radio: Optional[Literal['GSM', 'UMTS', 'LTE', 'NR', 'NBIOT', 'CDMA']]#
channel: ChannelRange | None#
defaults: AntennaDefaults#
scene_or_area()[source]#
Return type:

AntennaRequest

class openworld_radio_twin.models.AntennaResponse(**data)[source]#

Bases: BaseModel

Selected antennas, with the operators, radios and channels present before selection.

scene_id is set when the antennas are placed in a compiled scene and None for an area on the map, where position stays unset. channel is the selected channel.

scene_id: str | None#
antennas: list[AntennaFeature]#
operators: list[AntennaOperator]#
radios: list[Literal['GSM', 'UMTS', 'LTE', 'NR', 'NBIOT', 'CDMA']]#
channels: list[Channel]#
channel: ChannelRange | None#
defaults: AntennaDefaults#
warnings: list[str]#
data_provenance: dict[str, str | int | float | bool]#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openworld_radio_twin.models.SearchResult(**data)[source]#

Bases: BaseModel

display_name: str#
latitude: float#
longitude: float#
kind: str | None#
model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].