import math
from enum import Enum
from typing import Literal
import numpy as np
from pydantic import (
BaseModel,
ConfigDict,
Field,
computed_field,
field_validator,
model_validator,
)
from openworld_radio_twin.geodesy import LocalFrame
from openworld_radio_twin.spectrum import DOWNLINK_LINKS, Link, classify_ranges
[docs]
class EngineName(str, Enum):
preview = "preview"
sionna = "sionna"
MAX_PREVIEW_GRID_CELLS = 20_000
MAX_SIONNA_GRID_CELLS = 2_250_000
MAX_TERRAIN_GRID_CELLS = 250_000
MAX_SAMPLES_PER_TX = 100_000_000
# Transmitters share two budgets instead of a fixed count. Transmitters times receiver
# cells bounds radio-map memory and preview work; transmitters times ray samples bounds
# Sionna run time. Each equals what eight transmitters at the largest grid allowed.
MAX_PREVIEW_TRANSMITTER_CELLS = 8 * MAX_PREVIEW_GRID_CELLS
MAX_SIONNA_TRANSMITTER_CELLS = 8 * MAX_SIONNA_GRID_CELLS
MAX_SIONNA_RAY_SAMPLES = 8 * MAX_SAMPLES_PER_TX
# Carrier frequencies for which Sionna's ITU radio materials, ground included, are defined.
SIONNA_FREQUENCY_RANGE_GHZ = (1.0, 10.0)
SOURCE_ID_PATTERN = r"^(?:[a-z][a-z0-9_-]*|3dbag)$"
# Where a value of an antenna or of a transmitter taken from one came from; ``user`` marks a
# value edited in the explorer.
ValueBasis = Literal["source", "derived", "default", "adjusted", "user"]
RadioTechnology = Literal["GSM", "UMTS", "LTE", "NR", "NBIOT", "CDMA"]
[docs]
class Coordinate(BaseModel):
latitude: float = Field(ge=-90, le=90)
longitude: float = Field(ge=-180, le=180)
altitude_m: float = Field(
default=25.0,
ge=0,
le=1000,
description="Transmitter height above the local ground plane in meters (AGL)",
)
[docs]
class TransmitterSource(BaseModel):
"""The antenna record a transmitter was taken from, and where each value came from."""
feature_id: str
source: str
release: str | None = None
basis: dict[str, ValueBasis] = Field(default_factory=dict)
[docs]
class TransmitterConfig(BaseModel):
position: Coordinate
frequency_ghz: float = Field(default=3.5, ge=0.1, le=100)
power_dbm: float = Field(default=30.0, ge=-20, le=80)
azimuth_deg: float = Field(default=0.0, ge=0, lt=360)
downtilt_deg: float = Field(default=6.0, ge=-30, le=90)
antenna_pattern: str = Field(default="sector", pattern="^(sector|isotropic)$")
source: TransmitterSource | None = None
SIONNA_PROPAGATION_PARAMETERS = (
"los",
"specular_reflection",
"diffuse_reflection",
"refraction",
"diffraction",
"edge_diffraction",
"diffraction_lit_region",
)
[docs]
class SionnaEngineConfig(BaseModel):
"""Runtime and geometry controls for the built-in Sionna RT adapter."""
model_config = ConfigDict(extra="forbid")
device: Literal["auto", "cuda", "cpu"] = "auto"
include_ground: bool = True
include_vegetation: bool = True
include_paved: bool = True
include_water: bool = True
include_building_roofs: bool = True
include_building_walls: bool = True
# Names and defaults follow Sionna RT 2.0.1 RadioMapSolver.__call__.
los: bool = True
specular_reflection: bool = True
diffuse_reflection: bool = False
refraction: bool = True
diffraction: bool = False
edge_diffraction: bool = False
diffraction_lit_region: bool = True
[docs]
class SceneRequest(BaseModel):
"""Geometry inputs of a compiled scene, keyed like ``openworld_radio_twin.rt.load_scene``."""
latitude: float = Field(ge=-90, le=90)
longitude: float = Field(ge=-180, le=180)
radius_m: float = Field(default=750, ge=100, le=5000)
include_buildings: bool = True
building_source: str = Field(default="auto", pattern=SOURCE_ID_PATTERN)
include_terrain: bool = False
material_profile: Literal["itu", "uniform"] = "itu"
terrain_resolution_m: float = Field(
default=5.0,
ge=1.0,
le=100.0,
description="ENU terrain mesh spacing; distinct from source DEM resolution",
)
[docs]
@model_validator(mode="after")
def limit_terrain_grid(self) -> "SceneRequest":
terrain_side = math.ceil(2 * self.radius_m / self.terrain_resolution_m)
if self.include_terrain and terrain_side**2 > MAX_TERRAIN_GRID_CELLS:
raise ValueError(
f"Requested {terrain_side}x{terrain_side} terrain grid exceeds the "
f"{MAX_TERRAIN_GRID_CELLS:,}-cell viewer and scene limit; "
"increase terrain resolution"
)
return self
@property
def buildings_mode(self) -> Literal["auto", "none"]:
return "auto" if self.include_buildings else "none"
@property
def terrain_mode(self) -> Literal["elevation", "flat"]:
return "elevation" if self.include_terrain else "flat"
[docs]
class SceneCenter(BaseModel):
"""Explicit scene origin; the compiled square is centred here rather than on the first TX."""
latitude: float = Field(ge=-90, le=90)
longitude: float = Field(ge=-180, le=180)
[docs]
class SimulationRequest(BaseModel):
transmitters: list[TransmitterConfig] = Field(min_length=1)
scene_center: SceneCenter | None = Field(
default=None,
description=(
"Centre of the compiled scene square. Defaults to the first transmitter; "
"dataset generation sets it to the scene centre."
),
)
engine: str = Field(default=EngineName.preview.value, pattern=r"^[a-z][a-z0-9-]*$")
engine_config: dict[str, str | int | float | bool] = Field(default_factory=dict)
radius_m: float = Field(default=750, ge=100, le=5000)
resolution_m: float = Field(default=30, ge=0.1, le=200)
receiver_height_m: float = Field(
default=1.5,
ge=0.1,
le=100,
description="Receiver height above the local ground plane in meters (AGL)",
)
max_depth: int = Field(default=3, ge=0, le=8)
samples_per_tx: int = Field(default=1_000_000, ge=10_000, le=MAX_SAMPLES_PER_TX)
seed: int = Field(default=42, ge=0, le=4_294_967_295)
association_metric: str = Field(default="sinr", pattern="^(path_gain|rss|sinr)$")
bandwidth_mhz: float = Field(
default=1.0,
gt=0,
description="Receiver noise bandwidth in MHz; 1 MHz is Sionna's default",
)
include_buildings: bool = True
building_source: str = Field(default="auto", pattern=SOURCE_ID_PATTERN)
include_terrain: bool = False
material_profile: Literal["itu", "uniform"] = "itu"
terrain_resolution_m: float = Field(
default=5.0,
ge=1.0,
le=100.0,
description="ENU terrain mesh spacing; distinct from source DEM resolution",
)
[docs]
@model_validator(mode="after")
def limit_grid_size(self) -> "SimulationRequest":
terrain_side = math.ceil(2 * self.radius_m / self.terrain_resolution_m)
if self.include_terrain and terrain_side**2 > MAX_TERRAIN_GRID_CELLS:
raise ValueError(
f"Requested {terrain_side}x{terrain_side} terrain grid exceeds the "
f"{MAX_TERRAIN_GRID_CELLS:,}-cell viewer and scene limit; "
"increase terrain resolution"
)
side = math.ceil(2 * self.radius_m / self.resolution_m)
maximum = (
MAX_PREVIEW_GRID_CELLS
if self.engine == EngineName.preview.value
else MAX_SIONNA_GRID_CELLS
)
if side**2 > maximum:
raise ValueError(
f"Requested {side}x{side} coverage grid exceeds the "
f"{maximum:,}-cell {self.engine} limit; increase resolution"
)
count = len(self.transmitters)
cell_budget = (
MAX_PREVIEW_TRANSMITTER_CELLS
if self.engine == EngineName.preview.value
else MAX_SIONNA_TRANSMITTER_CELLS
)
if count * side**2 > cell_budget:
raise ValueError(
f"{count} transmitters on a {side}x{side} grid exceed the {cell_budget:,} "
f"transmitter-cell budget of {self.engine}; increase the resolution or "
"use fewer transmitters"
)
if (
self.engine == EngineName.sionna.value
and count * self.samples_per_tx > MAX_SIONNA_RAY_SAMPLES
):
raise ValueError(
f"{count} transmitters with {self.samples_per_tx:,} samples each exceed the "
f"{MAX_SIONNA_RAY_SAMPLES:,}-sample Sionna budget; reduce the samples per "
"transmitter or use fewer transmitters"
)
origin = self.scene_origin
frame = LocalFrame.at(origin.longitude, origin.latitude)
for index, transmitter in enumerate(self.transmitters, start=1):
east, north, _ = frame.to_local(
transmitter.position.longitude, transmitter.position.latitude
)
if max(abs(east), abs(north)) > self.radius_m + 1e-6:
raise ValueError(
f"Transmitter {index} lies outside the {2 * self.radius_m:g} m scene square"
)
if self.engine == EngineName.sionna.value:
self.engine_config = SionnaEngineConfig.model_validate(self.engine_config).model_dump()
frequencies = {transmitter.frequency_ghz for transmitter in self.transmitters}
patterns = {transmitter.antenna_pattern for transmitter in self.transmitters}
lowest, highest = SIONNA_FREQUENCY_RANGE_GHZ
if any(not lowest <= frequency <= highest for frequency in frequencies):
raise ValueError(
f"The default Sionna ITU ground model is valid from {lowest:g} to "
f"{highest:g} GHz"
)
if len(frequencies) != 1:
raise ValueError("Sionna transmitters must use one shared scene frequency")
if len(patterns) != 1:
raise ValueError("Sionna transmitters must use one shared antenna pattern")
return self
@property
def include_surface_materials(self) -> 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.
"""
return self.material_profile == "itu"
@property
def include_environment_grid(self) -> 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.
"""
if self.include_terrain:
return True
return self.include_surface_materials and self.engine == EngineName.sionna.value
@property
def reference_transmitter(self) -> TransmitterConfig:
"""First TX; it sets the shared antenna preset and, without ``scene_center``, the origin."""
return self.transmitters[0]
@property
def scene_origin(self) -> SceneCenter:
"""Local ENU origin and coverage-grid centre of the compiled scene."""
if self.scene_center is not None:
return self.scene_center
position = self.reference_transmitter.position
return SceneCenter(latitude=position.latitude, longitude=position.longitude)
@property
def scene_request(self) -> SceneRequest:
"""Geometry of the compiled scene this simulation runs in."""
origin = self.scene_origin
return SceneRequest(
latitude=origin.latitude,
longitude=origin.longitude,
radius_m=self.radius_m,
include_buildings=self.include_buildings,
building_source=self.building_source,
include_terrain=self.include_terrain,
material_profile=self.material_profile,
terrain_resolution_m=self.terrain_resolution_m,
)
[docs]
class BuildingGeometry(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 = Field(allow_inf_nan=False)
vertices: list[tuple[float, float, float]] = Field(min_length=3)
triangles: list[tuple[int, int, int]] = Field(min_length=1)
surface_types: list[str]
[docs]
@model_validator(mode="after")
def validate_mesh(self) -> "BuildingGeometry":
vertices = np.asarray(self.vertices, dtype=np.float64).reshape(-1, 3)
if not np.isfinite(vertices).all():
raise ValueError("Building geometry coordinates must be finite")
if len(self.surface_types) != len(self.triangles):
raise ValueError("Each building triangle needs a surface type")
triangles = np.asarray(self.triangles, dtype=np.int64).reshape(-1, 3)
if (
(triangles < 0).any()
or (triangles >= len(self.vertices)).any()
or (triangles[:, 0] == triangles[:, 1]).any()
or (triangles[:, 1] == triangles[:, 2]).any()
or (triangles[:, 0] == triangles[:, 2]).any()
):
raise ValueError("Building geometry has an invalid triangle index")
return self
[docs]
class BuildingFeature(BaseModel):
feature_id: str
source: str
feature_type: str = Field(default="building", pattern="^(building|building_part)$")
source_dataset_id: str | None = None
parent_building_id: str | None = None
source_record_id: str | None = None
source_release: str | None = None
name: str | None = None
height_m: float = Field(
gt=0,
le=1000,
description="Vertical extent from the feature's lowest to highest point in meters",
)
min_height_m: float = Field(
default=0,
ge=0,
le=1000,
description="Height AGL at which the feature begins",
)
height_source: str = "unspecified"
height_uncertainty_m: float | None = None
coordinates: list[list[float]]
holes: list[list[list[float]]] = Field(default_factory=list)
geometry: BuildingGeometry | None = None
source_attributes: dict[str, object] = Field(default_factory=dict)
@computed_field
@property
def roof_height_agl_m(self) -> float:
return self.min_height_m + self.height_m
[docs]
class FrequencyRange(BaseModel):
"""A frequency range in MHz, kept to 1 kHz."""
low_mhz: float = Field(gt=0)
high_mhz: float = Field(gt=0)
[docs]
@field_validator("low_mhz", "high_mhz")
@classmethod
def to_kilohertz(cls, value: float) -> float:
# Registers in kHz scale to MHz with float noise (1805100 x 0.001 = 1805.1000000000001).
return round(value, 3)
[docs]
@model_validator(mode="after")
def ordered(self) -> "FrequencyRange":
if self.high_mhz < self.low_mhz:
raise ValueError("A frequency range must end at or above its start")
return self
@property
def width_mhz(self) -> float:
return self.high_mhz - self.low_mhz
@property
def centre_hz(self) -> float:
"""The centre frequency in Hz, the value of Sionna's ``scene.frequency``."""
return (self.low_mhz + self.high_mhz) / 2 * 1e6
@property
def bandwidth_hz(self) -> float:
"""The width in Hz, the value of Sionna's ``scene.bandwidth``."""
return self.width_mhz * 1e6
[docs]
def contains(self, other: "FrequencyRange") -> bool:
return self.low_mhz <= other.low_mhz and other.high_mhz <= self.high_mhz
[docs]
def covers(self, frequency_hz: float) -> bool:
return self.low_mhz <= frequency_hz / 1e6 <= self.high_mhz
def _stated_link(stated: set[str | None], classified: Link) -> Link:
"""The direction every band of a range states, else the 3GPP classification."""
if len(stated) == 1 and None not in stated:
return next(iter(stated))
return classified
[docs]
class FrequencyBand(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
link: Link | None = None
[docs]
class Emission(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
:mod:`openworld_radio_twin.spectrum`.
"""
link: Link
labels: list[str]
[docs]
class ChannelRange(FrequencyRange):
"""A downlink channel to simulate: ``centre_hz`` is Sionna's ``scene.frequency`` and
``bandwidth_hz`` its ``scene.bandwidth``."""
[docs]
@model_validator(mode="after")
def usable_width(self) -> "ChannelRange":
if self.width_mhz <= 0:
raise ValueError("A channel needs a width above 0")
return self
[docs]
class Channel(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
:data:`SIONNA_FREQUENCY_RANGE_GHZ`.
"""
labels: list[str]
operators: list[str]
antenna_count: int
sionna_supported: bool
[docs]
class AntennaFeature(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
:class:`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 = None
site_id: str
operator: str | None = None
plmn: str | None = Field(default=None, pattern=r"^\d{3}-\d{2,3}$")
radios: list[RadioTechnology] = Field(default_factory=list)
bands: list[FrequencyBand] = Field(default_factory=list)
latitude: float = Field(ge=-90, le=90)
longitude: float = Field(ge=-180, le=180)
height_agl_m: float | None = Field(default=None, ge=0, le=1000)
azimuth_deg: float | None = Field(default=None, ge=0, lt=360)
downtilt_deg: float | None = Field(default=None, ge=-90, le=90)
power_dbm: float | None = Field(default=None, ge=-20, le=80)
basis: dict[str, ValueBasis] = Field(default_factory=dict)
position: tuple[float, float, float] | None = None
orientation: tuple[float, float, float] | None = None
source_attributes: dict[str, object] = Field(default_factory=dict)
@property
def operator_id(self) -> str:
"""The value the operator selection matches: the PLMN, else the operator name."""
return self.plmn or self.operator or "unknown"
@property
def emissions(self) -> list[Emission]:
"""The antenna's distinct registered ranges, each with its link direction."""
labels: dict[tuple[float, float], set[str]] = {}
stated: dict[tuple[float, float], set[str | None]] = {}
for band in self.bands:
key = (band.low_mhz, band.high_mhz)
labels.setdefault(key, set()).add(band.label)
stated.setdefault(key, set()).add(band.link)
ranges = tuple(sorted(labels))
return [
Emission(
low_mhz=low,
high_mhz=high,
link=_stated_link(stated[(low, high)], link),
labels=sorted(labels[(low, high)]),
)
for (low, high), link in zip(ranges, classify_ranges(ranges), strict=True)
]
[docs]
def transmits_on(self, channel: FrequencyRange) -> bool:
"""Whether a downlink or TDD range the antenna registers contains ``channel``."""
return any(
emission.link in DOWNLINK_LINKS and emission.contains(channel)
for emission in self.emissions
)
[docs]
class AntennaDefaults(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 = ConfigDict(extra="forbid")
height_agl_m: float = Field(default=25.0, ge=0, le=1000)
azimuth_deg: float = Field(default=90.0, ge=0, lt=360)
downtilt_deg: float = Field(default=0.0, ge=-30, le=90)
power_dbm: float = Field(default=44.0, ge=-20, le=80)
sectors: tuple[float, ...] | None = None
roof_clearance_m: float = Field(default=1.0, ge=0, le=50)
[docs]
@model_validator(mode="after")
def valid_sectors(self) -> "AntennaDefaults":
if self.sectors is not None and (
not self.sectors or any(not 0 <= azimuth < 360 for azimuth in self.sectors)
):
raise ValueError("Sector azimuths must be one or more angles in [0, 360)")
return self
[docs]
class GridMapping(BaseModel):
horizontal_datum: str = "WGS84"
local_axes: str = "east,north,up"
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]]
[docs]
class RadioLayer(BaseModel):
label: str
unit: str
values: list[float | None] | None = None
minimum: float
maximum: float
display_minimum: float
display_maximum: float
reduction: str = "best_transmitter_per_cell"
[docs]
class CoverageGrid(BaseModel):
crs: str = "EPSG:4326"
no_data_value: None = 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 = None
building_mask: list[bool] | None = None
building_heights_m: list[float | None] | None = None
building_cell_count: int = 0
[docs]
@model_validator(mode="after")
def validate_aligned_grids(self) -> "CoverageGrid":
arrays = [self.association, self.building_mask, self.building_heights_m]
arrays.extend(layer.values for layer in self.layers.values())
if all(value is None for value in arrays):
return self
if any(value is None for value in arrays):
raise ValueError("Coverage cell arrays must be either all present or all omitted")
assert self.association is not None
assert self.building_mask is not None
assert self.building_heights_m is not None
expected = self.width * self.height
aligned = {
"association": len(self.association),
"building_mask": len(self.building_mask),
"building_heights_m": len(self.building_heights_m),
}
for name, layer in self.layers.items():
assert layer.values is not None
aligned[f"layers.{name}"] = len(layer.values)
for name, actual in aligned.items():
if actual != expected:
raise ValueError(f"{name} has {actual} cells; expected {expected}")
if any(
mask != (height is not None)
for mask, height in zip(self.building_mask, self.building_heights_m, strict=True)
):
raise ValueError("building_mask and building_heights_m disagree")
return self
[docs]
class NativeBuildingMesh(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
[docs]
class BuildingGeometryContext(BaseModel):
"""Solver-coordinate native shells, with no visual offset or vertical scaling."""
origin_longitude: float
origin_latitude: float
coordinate_system: str = "WGS84 topocentric ENU"
meshes: list[NativeBuildingMesh]
[docs]
class SimulationResponse(BaseModel):
simulation_id: str
engine: str
elapsed_ms: int
coverage: CoverageGrid
buildings: list[BuildingFeature]
building_geometry: BuildingGeometryContext | None = None
warnings: list[str] = Field(default_factory=list)
engine_details: dict[str, str | int | float | bool] = Field(default_factory=dict)
data_provenance: dict[str, str | int | float | bool] = Field(default_factory=dict)
environment: "EnvironmentContext | None" = None
scene: "SceneResponse | None" = None
[docs]
class SceneBounds(BaseModel):
origin_longitude: float
origin_latitude: float
radius_m: float
wgs84_corners: list[list[float]]
[docs]
class SceneResponse(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 = None
environment: "EnvironmentContext | None" = None
warnings: list[str] = Field(default_factory=list)
data_provenance: dict[str, str | int | float | bool] = Field(default_factory=dict)
[docs]
class TerrainContext(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]
[docs]
class SurfaceContext(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]
[docs]
class EnvironmentContext(BaseModel):
terrain: TerrainContext
surfaces: SurfaceContext
[docs]
class BuildingContextResponse(BaseModel):
buildings: list[BuildingFeature]
building_geometry: BuildingGeometryContext | None = None
warnings: list[str] = Field(default_factory=list)
data_provenance: dict[str, str | int | float | bool] = Field(default_factory=dict)
[docs]
class AntennaOperator(BaseModel):
"""An operator present in a scene; ``id`` is the value the operator filter takes."""
id: str
name: str
count: int
[docs]
class AntennaRequest(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 = ConfigDict(extra="forbid")
scene_id: str | None = None
latitude: float | None = Field(default=None, ge=-90, le=90)
longitude: float | None = Field(default=None, ge=-180, le=180)
radius_m: float | None = Field(default=None, ge=100, le=5000)
antenna_source: str = Field(default="auto", pattern=SOURCE_ID_PATTERN)
operator: str | None = Field(default=None, max_length=80)
radio: RadioTechnology | None = None
channel: ChannelRange | None = None
defaults: AntennaDefaults = Field(default_factory=AntennaDefaults)
[docs]
@model_validator(mode="after")
def scene_or_area(self) -> "AntennaRequest":
area = (self.latitude, self.longitude, self.radius_m)
if self.scene_id is not None and any(value is not None for value in area):
raise ValueError("Give either scene_id or latitude, longitude and radius_m")
if self.scene_id is None and any(value is None for value in area):
raise ValueError("Give scene_id, or latitude, longitude and radius_m together")
return self
[docs]
class AntennaResponse(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 = None
antennas: list[AntennaFeature]
operators: list[AntennaOperator]
radios: list[RadioTechnology]
channels: list[Channel]
channel: ChannelRange | None = None
defaults: AntennaDefaults
warnings: list[str] = Field(default_factory=list)
data_provenance: dict[str, str | int | float | bool] = Field(default_factory=dict)
[docs]
class SearchResult(BaseModel):
display_name: str
latitude: float
longitude: float
kind: str | None = None