Source code for openworld_radio_twin.cli

import argparse
import asyncio
from collections.abc import Sequence
from pathlib import Path

import httpx

from openworld_radio_twin.compiler import compile_scene_sync
from openworld_radio_twin.config import get_settings
from openworld_radio_twin.dataset import build_index, package_dataset
from openworld_radio_twin.providers.antenna_sources import default_antenna_sources
from openworld_radio_twin.providers.base import AntennaProviderError, BuildingProviderError
from openworld_radio_twin.providers.building_sources import default_building_sources
from openworld_radio_twin.providers.snapshots import current_snapshot, source_cache_root


def _add_server_arguments(parser: argparse.ArgumentParser) -> None:
    settings = get_settings()
    parser.add_argument("--host", default=settings.host)
    parser.add_argument("--port", type=int, default=settings.port)
    parser.add_argument("--reload", action="store_true")


def _serve(args: argparse.Namespace) -> None:
    try:
        import uvicorn
    except ImportError as exc:
        raise SystemExit(
            "The web server is not installed; install 'openworld-radio-twin[web]'"
        ) from exc
    uvicorn.run(
        "openworld_radio_twin.main:app",
        host=args.host,
        port=args.port,
        reload=args.reload,
    )


def _compile(args: argparse.Namespace) -> None:
    xml_path = compile_scene_sync(
        latitude=args.latitude,
        longitude=args.longitude,
        radius_m=args.radius,
        output=args.output,
        buildings=args.buildings,
        building_source=args.building_source,
        terrain=args.terrain,
        material_profile=args.material_profile,
        terrain_resolution_m=args.terrain_resolution,
        receiver_height_m=args.receiver_height,
        receiver_cell_size=tuple(args.receiver_cell_size),
        voxel_pitch_m=args.voxel_pitch,
        if_exists=args.if_exists,
    )
    print(xml_path)


def _registries():
    return default_building_sources(), default_antenna_sources()


def _sources_list(args: argparse.Namespace) -> None:
    settings = get_settings()
    for registry in _registries():
        for source in registry.describe(settings):
            # A source that pins an export keeps it in the directory named by its ID.
            snapshot = current_snapshot(source_cache_root(settings) / str(source["id"]))
            state = (
                "configured"
                if source["configured"]
                else f"not configured: {source['configuration_hint']}"
            )
            installed = f"; snapshot {snapshot.identity}" if snapshot else ""
            print(f"{registry.kind:<9} {source['id']:<14} {source['title']} ({state}{installed})")


async def _refresh(identifier: str) -> str:
    settings = get_settings()
    sources = []
    for registry in _registries():
        try:
            sources.append(registry.get(identifier))
        except ValueError:
            pass
    if not sources:
        raise SystemExit(f"Unknown source: {identifier}")
    async with httpx.AsyncClient(
        follow_redirects=True, timeout=settings.http_request_timeout_seconds
    ) as client:
        for source in sources:
            provider = source.factory(settings, client)
            if hasattr(provider, "snapshot"):
                snapshot = await provider.snapshot(refresh=True)
                rows = snapshot.metadata["rows"]
                return f"{identifier}: snapshot {snapshot.identity}, {rows:,} records"
    raise SystemExit(f"Source '{identifier}' has no downloadable snapshot")


def _sources_refresh(args: argparse.Namespace) -> None:
    try:
        print(asyncio.run(_refresh(args.source)))
    except (AntennaProviderError, BuildingProviderError, ValueError) as exc:
        raise SystemExit(str(exc)) from None


def _split_fractions(value: str) -> dict[str, float]:
    fractions = {}
    for item in value.split(","):
        name, separator, fraction = item.partition("=")
        try:
            fractions[name.strip()] = float(fraction)
        except ValueError:
            separator = ""
        if not separator:
            raise argparse.ArgumentTypeError(
                f"expected NAME=FRACTION pairs separated by commas, got {item!r}"
            )
    return fractions


def _dataset_package(args: argparse.Namespace) -> None:
    try:
        output = package_dataset(
            args.dataset,
            args.output,
            fractions=args.split,
            seed=args.seed,
            skip_unreleasable=args.skip_unreleasable,
            previous=args.previous,
        )
    except (FileExistsError, FileNotFoundError, RuntimeError, ValueError) as exc:
        raise SystemExit(str(exc)) from None
    print(output)


def _dataset_index(args: argparse.Namespace) -> None:
    try:
        path = build_index(args.dataset)
    except (FileNotFoundError, RuntimeError, ValueError) as exc:
        raise SystemExit(str(exc)) from None
    print(path)


def _parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(prog="owrt", description="OpenWorld Radio Twin")
    _add_server_arguments(parser)
    commands = parser.add_subparsers(dest="command")

    serve = commands.add_parser("serve", help="Run the web application")
    _add_server_arguments(serve)
    serve.set_defaults(handler=_serve)

    scene = commands.add_parser("scene", help="Compile reusable geographic scenes")
    scene_commands = scene.add_subparsers(dest="scene_command", required=True)
    compile_parser = scene_commands.add_parser("compile", help="Compile a geographic scene")
    compile_parser.add_argument("--lat", dest="latitude", type=float, required=True)
    compile_parser.add_argument("--lon", dest="longitude", type=float, required=True)
    compile_parser.add_argument("--radius", type=float, required=True)
    compile_parser.add_argument("--output", type=Path, required=True)
    compile_parser.add_argument("--buildings", choices=("auto", "none"), default="auto")
    compile_parser.add_argument(
        "--building-source",
        default="auto",
        help="auto, global (Overture/OSM) or a source ID; see owrt sources list",
    )
    compile_parser.add_argument(
        "--terrain", choices=("elevation", "flat", "none"), default="elevation"
    )
    compile_parser.add_argument("--material-profile", choices=("itu", "uniform"), default="itu")
    compile_parser.add_argument("--terrain-resolution", type=float, default=5.0)
    compile_parser.add_argument("--receiver-height", type=float, default=1.5)
    compile_parser.add_argument(
        "--receiver-cell-size",
        type=float,
        nargs=2,
        metavar=("EAST_M", "NORTH_M"),
        default=(10.0, 10.0),
    )
    compile_parser.add_argument("--voxel-pitch", type=float, default=3.0)
    compile_parser.add_argument(
        "--if-exists", choices=("reuse", "error", "replace"), default="reuse"
    )
    compile_parser.set_defaults(handler=_compile)

    dataset = commands.add_parser("dataset", help="Index and package generated datasets")
    dataset_commands = dataset.add_subparsers(dest="dataset_command", required=True)
    index = dataset_commands.add_parser(
        "index", help="Rebuild a dataset's index.parquet, for example after a stopped run"
    )
    index.add_argument("dataset", type=Path, help="the generated dataset directory")
    index.set_defaults(handler=_dataset_index)
    package = dataset_commands.add_parser(
        "package", help="Package a dataset by scene with splits, licences and checksums"
    )
    package.add_argument("dataset", type=Path, help="the generated dataset directory")
    package.add_argument("output", type=Path, help="a new or empty package directory")
    package.add_argument(
        "--split",
        type=_split_fractions,
        default="train=0.8,validation=0.1,test=0.1",
        help="split fractions that add up to 1 (default: train=0.8,validation=0.1,test=0.1)",
    )
    package.add_argument("--seed", type=int, default=0, help="seed of the split shuffle")
    package.add_argument(
        "--skip-unreleasable",
        action="store_true",
        help="leave out scenes that may not be redistributed instead of refusing",
    )
    package.add_argument(
        "--previous",
        type=Path,
        help="an earlier package of the dataset, or its splits.json, whose splits are kept",
    )
    package.set_defaults(handler=_dataset_package)

    sources = commands.add_parser("sources", help="List data sources and refresh their snapshots")
    source_commands = sources.add_subparsers(dest="sources_command", required=True)
    source_commands.add_parser("list", help="List building and antenna sources").set_defaults(
        handler=_sources_list
    )
    refresh = source_commands.add_parser(
        "refresh", help="Download a source's latest export and pin it as the snapshot"
    )
    refresh.add_argument("source", help="a source ID with a snapshot; see owrt sources list")
    refresh.set_defaults(handler=_sources_refresh)
    return parser


[docs] def main(argv: Sequence[str] | None = None) -> None: parser = _parser() args = parser.parse_args(argv) if not hasattr(args, "handler"): _serve(args) return args.handler(args)
if __name__ == "__main__": main()