"""Antennas of a compiled scene: acquired from a source, selected, placed and recorded.
The Python loader, the web service and dataset generation all call
:func:`scene_antennas`, so a scene's antennas are the same wherever they are requested.
Each result is also written into the scene directory under ``antennas/`` as the record of
what the scene's transmitters were taken from; the compiled geometry does not change.
A Sionna run simulates one downlink channel: ``scene.frequency`` is its centre and
``scene.bandwidth`` its width. A channel is a downlink range an antenna registers, and an
antenna transmits on it when it registers a downlink range that contains it, at its own
power.
"""
from __future__ import annotations
import asyncio
import hashlib
import json
from collections.abc import Mapping, Sequence
from dataclasses import dataclass, replace
from pathlib import Path
import httpx
from openworld_radio_twin.compiler import _read_json, _scene_lock, _write_json_atomic
from openworld_radio_twin.config import Settings, get_settings
from openworld_radio_twin.jsonio import dump_json_with_compact_rows
from openworld_radio_twin.models import (
SIONNA_FREQUENCY_RANGE_GHZ,
AntennaDefaults,
AntennaFeature,
AntennaOperator,
Channel,
ChannelRange,
FrequencyRange,
TransmitterConfig,
)
from openworld_radio_twin.providers.base import ANTENNA_BOUNDARY_POLICY, AntennaQueryResult
from openworld_radio_twin.providers.map_data import MapDataProvider
from openworld_radio_twin.scene_format import SCENE_ANTENNAS_DIRECTORY, SCENE_INFO_PATH
from openworld_radio_twin.simulation.antenna_placement import (
complete_antennas,
keep_inside_scene,
keep_inside_square,
place_antennas,
)
from openworld_radio_twin.simulation.scene_builder import load_scene_assets
from openworld_radio_twin.spectrum import DOWNLINK_LINKS
# Version 2 renamed case_channels in a dataset scene's source_antennas.json.
ANTENNA_RECORD_SCHEMA_VERSION = 2
[docs]
@dataclass(frozen=True)
class SceneAntennas:
"""Selected antennas of a scene or map area, with the operators and radios it holds;
``record`` is the file written into a compiled scene, None for a map area."""
result: AntennaQueryResult
operators: list[AntennaOperator]
radios: list[str]
defaults: AntennaDefaults
record: Path | None
[docs]
def select_antennas(
result: AntennaQueryResult,
*,
operator: str | None = None,
radio: str | None = None,
) -> AntennaQueryResult:
"""Keep the antennas of one operator (PLMN or name) and radio technology."""
antennas = result.antennas
if operator:
wanted = operator.strip().casefold()
antennas = [
antenna
for antenna in antennas
if wanted in {(antenna.plmn or "").casefold(), (antenna.operator or "").casefold()}
]
if radio:
antennas = [antenna for antenna in antennas if radio.upper() in antenna.radios]
return replace(result, antennas=antennas)
[docs]
def downlink_channels(antennas: Sequence[AntennaFeature]) -> list[Channel]:
"""The distinct downlink and TDD ranges the antennas register, lowest first, each with
the antennas that transmit on it."""
downlinks = [
[emission for emission in antenna.emissions if emission.link in DOWNLINK_LINKS]
for antenna in antennas
]
ranges = sorted(
{
(emission.low_mhz, emission.high_mhz)
for emissions in downlinks
for emission in emissions
if emission.width_mhz > 0
}
)
lowest, highest = SIONNA_FREQUENCY_RANGE_GHZ
channels = []
for low, high in ranges:
channel = FrequencyRange(low_mhz=low, high_mhz=high)
labels: set[str] = set()
members = []
for antenna, emissions in zip(antennas, downlinks, strict=True):
containing = [emission for emission in emissions if emission.contains(channel)]
if containing:
members.append(antenna)
labels.update(label for emission in containing for label in emission.labels)
channels.append(
Channel(
low_mhz=low,
high_mhz=high,
labels=sorted(labels),
operators=sorted({antenna.operator_id for antenna in members}),
antenna_count=len(members),
sionna_supported=lowest <= (low + high) / 2000 <= highest,
)
)
return channels
[docs]
def summarize_antennas(
antennas: Sequence[AntennaFeature],
) -> tuple[list[AntennaOperator], list[str], list[Channel]]:
"""Operators, radios and downlink channels present among ``antennas``."""
operators: dict[str, list[str | int]] = {}
radios: set[str] = set()
for antenna in antennas:
if antenna.operator and antenna.plmn:
name = f"{antenna.operator} ({antenna.plmn})"
else:
name = antenna.operator or antenna.plmn or "Unknown operator"
operators.setdefault(antenna.operator_id, [name, 0])[1] += 1
radios.update(antenna.radios)
return (
sorted(
(
AntennaOperator(id=identifier, name=str(name), count=int(count))
for identifier, (name, count) in operators.items()
),
key=lambda item: (-item.count, item.name),
),
sorted(radios),
downlink_channels(antennas),
)
[docs]
def as_channel(value: ChannelRange | Mapping[str, float] | Sequence[float]) -> ChannelRange:
"""A channel given as a range, a ``{"low_mhz", "high_mhz"}`` mapping or ``(low, high)``."""
if isinstance(value, FrequencyRange):
return ChannelRange(low_mhz=value.low_mhz, high_mhz=value.high_mhz)
if isinstance(value, Mapping):
return ChannelRange.model_validate(dict(value))
low, high = value
return ChannelRange(low_mhz=low, high_mhz=high)
[docs]
def select_channel(
result: AntennaQueryResult, channel: ChannelRange | Mapping[str, float] | Sequence[float]
) -> AntennaQueryResult:
"""Keep the antennas that transmit on ``channel``: those registering a downlink or TDD
range that contains it, whatever operator or technology, at their own power. An antenna
that registers no frequencies, as with OpenCelliD, is assumed to transmit on it and is
counted in a warning."""
channel = as_channel(channel)
unregistered = [antenna for antenna in result.antennas if not antenna.bands]
kept = [
antenna for antenna in result.antennas if not antenna.bands or antenna.transmits_on(channel)
]
warnings = list(result.warnings)
if unregistered:
warnings.append(
f"{len(unregistered)} antennas register no frequencies; they are assumed to "
"transmit on the selected channel."
)
return replace(result, antennas=kept, warnings=warnings, channel=channel)
[docs]
def transmitter_config(
antenna: AntennaFeature,
*,
frequency_ghz: float,
antenna_pattern: str,
) -> TransmitterConfig:
"""A placed antenna as a transmitter of a simulation request, with its provenance."""
return TransmitterConfig.model_validate(
{
"position": {
"latitude": antenna.latitude,
"longitude": antenna.longitude,
"altitude_m": antenna.height_agl_m,
},
"frequency_ghz": frequency_ghz,
"power_dbm": antenna.power_dbm,
"azimuth_deg": antenna.azimuth_deg,
"downtilt_deg": antenna.downtilt_deg,
"antenna_pattern": antenna_pattern,
"source": {
"feature_id": antenna.feature_id,
"source": antenna.source,
"release": antenna.source_release,
"basis": antenna.basis,
},
}
)
def _record_payload(result: AntennaQueryResult, query: Mapping[str, object]) -> dict:
return {
"schema_version": ANTENNA_RECORD_SCHEMA_VERSION,
"query": dict(query),
"source_selection": result.source_selection,
"provider": result.provider,
"release": result.release,
"attribution": result.attribution,
"license": result.license,
"license_url": result.license_url,
"boundary_policy": ANTENNA_BOUNDARY_POLICY,
"boundary_excluded_count": result.boundary_excluded_count,
"warnings": result.warnings,
"channel": result.channel.model_dump(mode="json") if result.channel else None,
"antennas": [antenna.model_dump(mode="json") for antenna in result.antennas],
}
[docs]
def write_antenna_record(
directory: Path, result: AntennaQueryResult, query: Mapping[str, object]
) -> Path:
"""Write the selection into ``antennas/`` and list it in ``scene_info.json``."""
identity = json.dumps(
{"query": query, "source_selection": result.source_selection, "release": result.release},
sort_keys=True,
default=str,
)
resolved = str(result.source_selection.get("resolved", "none"))
name = f"{resolved}-{hashlib.sha256(identity.encode()).hexdigest()[:16]}.json"
target = directory / SCENE_ANTENNAS_DIRECTORY / name
with _scene_lock(directory):
target.parent.mkdir(exist_ok=True)
dump_json_with_compact_rows(target, _record_payload(result, query), "antennas")
info_path = directory / SCENE_INFO_PATH
if info_path.is_file():
info = _read_json(info_path)
shared = info.setdefault("shared_assets", {})
relative = target.relative_to(directory).as_posix()
records = [item for item in shared.get("antenna_records", []) if item != relative]
shared["antenna_records"] = [*records, relative]
_write_json_atomic(info_path, info)
return target
[docs]
def write_antenna_source(
path: Path,
result: AntennaQueryResult,
query: Mapping[str, object],
channels: Sequence[ChannelRange],
) -> None:
"""Persist a dataset scene's selected source records, before any placement, with the
channels its radio maps draw from."""
payload = {
**_record_payload(result, query),
"radio_map_channels": [channel.model_dump(mode="json") for channel in channels],
}
dump_json_with_compact_rows(path, payload, "antennas")
[docs]
def load_antenna_source(
path: Path,
) -> tuple[AntennaQueryResult, dict[str, object], list[ChannelRange]]:
"""Read records written by :func:`write_antenna_source`, with the query that chose them
and the channels of the scene's radio maps."""
value = _read_json(path)
result = AntennaQueryResult(
antennas=[AntennaFeature.model_validate(item) for item in value["antennas"]],
provider=str(value["provider"]),
release=value.get("release"),
warnings=[str(item) for item in value.get("warnings", [])],
boundary_excluded_count=int(value.get("boundary_excluded_count", 0)),
source_selection=value.get("source_selection", {}),
attribution=str(value.get("attribution", "")),
license=str(value.get("license", "")),
license_url=str(value.get("license_url", "")),
)
channels = [
ChannelRange.model_validate(item) for item in value.get("radio_map_channels", [])
]
return result, dict(value.get("query", {})), channels
[docs]
async def scene_antennas(
directory: Path,
provider: MapDataProvider,
*,
source: str = "auto",
operator: str | None = None,
radio: str | None = None,
channel: ChannelRange | Mapping[str, float] | Sequence[float] | None = None,
defaults: AntennaDefaults | Mapping[str, object] | None = None,
) -> SceneAntennas:
"""Acquire, place and select the antennas inside a compiled scene, and record them."""
if not isinstance(defaults, AntennaDefaults):
defaults = AntennaDefaults.model_validate(dict(defaults or {}))
channel = as_channel(channel) if channel is not None else None
assets = await asyncio.to_thread(load_scene_assets, directory)
acquired = await provider.antennas(
assets.origin_latitude, assets.origin_longitude, assets.radius_m, source=source
)
inside = keep_inside_scene(acquired, assets)
operators, radios, channels = summarize_antennas(inside.antennas)
chosen = select_antennas(inside, operator=operator, radio=radio)
if channel is not None:
chosen = select_channel(chosen, channel)
selected = await asyncio.to_thread(place_antennas, chosen, assets, defaults)
selected = replace(selected, channels=channels)
query = {
"source": source,
"operator": operator,
"radio": radio,
"channel": channel.model_dump(mode="json") if channel else None,
"defaults": defaults.model_dump(mode="json"),
}
record = await asyncio.to_thread(write_antenna_record, directory, selected, query)
return SceneAntennas(selected, operators, radios, defaults, record)
[docs]
async def area_antennas(
provider: MapDataProvider,
latitude: float,
longitude: float,
radius_m: float,
*,
source: str = "auto",
operator: str | None = None,
radio: str | None = None,
channel: ChannelRange | Mapping[str, float] | Sequence[float] | None = None,
defaults: AntennaDefaults | Mapping[str, object] | None = None,
) -> SceneAntennas:
"""Antennas inside a square on the map, completed with defaults but not placed.
Placement needs the terrain and buildings of a compiled scene; this view needs neither,
so the explorer can show a source's antennas before a scene exists. Nothing is recorded.
"""
if not isinstance(defaults, AntennaDefaults):
defaults = AntennaDefaults.model_validate(dict(defaults or {}))
channel = as_channel(channel) if channel is not None else None
acquired = await provider.antennas(latitude, longitude, radius_m, source=source)
inside = keep_inside_square(acquired, longitude, latitude, radius_m)
operators, radios, channels = summarize_antennas(inside.antennas)
chosen = select_antennas(inside, operator=operator, radio=radio)
if channel is not None:
chosen = select_channel(chosen, channel)
selected = complete_antennas(chosen, defaults)
return SceneAntennas(replace(selected, channels=channels), operators, radios, defaults, None)
[docs]
async def load_scene_antennas(
directory: Path,
*,
settings: Settings | None = None,
provider: MapDataProvider | None = None,
**selection: object,
) -> SceneAntennas:
""":func:`scene_antennas` with a provider of its own when the caller has none."""
if provider is not None:
return await scene_antennas(directory, provider, **selection)
runtime_settings = settings or get_settings()
async with httpx.AsyncClient(
follow_redirects=True, timeout=runtime_settings.http_request_timeout_seconds
) as client:
return await scene_antennas(
directory, MapDataProvider(runtime_settings, client), **selection
)