Source code for openworld_radio_twin.conventions

"""Row orders, units, no-data values and data types of the written arrays.

The product writers import these constants, and the dataset manifest records them as its
``conventions`` block, so each product's metadata and the manifest state the same values.
"""

from types import MappingProxyType

from openworld_radio_twin.environment import SurfaceClass
from openworld_radio_twin.scene_format import (
    SCENE_HEIGHT_MAP_PATH,
    SCENE_MEASUREMENT_SURFACES_DIRECTORY,
)

# Dataset format written into the manifest, the plan, scene_info.json, every
# radio_map_info.json and the index. Format 1 stored radio maps as ``cases``.
DATASET_SCHEMA_VERSION = 2

SOUTH_TO_NORTH = "south_to_north"
NORTH_TO_SOUTH = "north_to_south"
WEST_TO_EAST = "west_to_east"
LENGTH_UNIT = "m"
# Transmitter ``altitude_m`` and the receiver height are both above the local ground.
HEIGHT_REFERENCE = "terrain AGL"

# Radio arrays hold linear values with row zero at the south edge. A cell without coverage
# holds 0; RadioMapData rejects NaN and infinite values.
RADIO_ARRAY_DTYPE = "float32"
RADIO_ARRAY_AXIS_ORDER = ("transmitter", "south_to_north_row", "west_to_east_column")
RADIO_ENGINE_ARRAY_CONTRACT = f"linear_{RADIO_ARRAY_DTYPE}_(n_tx,rows,columns)"
RADIO_METRIC_UNITS = MappingProxyType(
    {"path_gain": "linear ratio", "rss": "W", "sinr": "linear ratio"}
)
RADIO_IMAGE_UNITS = MappingProxyType({"path_gain": "dB", "rss": "dBm", "sinr": "dB"})

# The association array holds, per cell, the index of the serving transmitter in the request's
# transmitter list under the recorded association metric, on the radio array grid.
ASSOCIATION_ARRAY_PATH = "arrays/association/association.npz"
ASSOCIATION_DTYPE = "int32"
ASSOCIATION_UNIT = "transmitter index"
ASSOCIATION_NO_SERVICE = -1

# A dataset stores one radio array per radio map: path gain in dB, packed into unsigned 16-bit
# integers with CF-style attributes. A positive linear gain PG is stored as
# round((10 * log10(PG) - add_offset) / scale_factor), rounding half to even; PG == 0 is stored
# as the fill value and means that the transmitter contributes nothing to the cell. RSS, SINR
# and the serving transmitter are derived on load from the path gain and the record's ``radio``
# block.
PATH_GAIN_ARRAY_PATH = "arrays/path_gain/path_gain.npz"
PATH_GAIN_KEY = "path_gain"
PATH_GAIN_DTYPE = "<u2"
PATH_GAIN_UNITS = "dB"
PATH_GAIN_SCALE_FACTOR = 0.01
PATH_GAIN_ADD_OFFSET = -500.0
PATH_GAIN_FILL_VALUE = 0
PATH_GAIN_VALID_RANGE = (1, 65535)

# Every PNG is north-up; the radio images are the radio arrays flipped. A radio map keeps its
# PNG previews in this directory.
RADIO_IMAGES_DIRECTORY = "images"
IMAGE_ROW_ORDER = NORTH_TO_SOUTH
IMAGE_NO_DATA_RENDERING = "transparent"

MEASUREMENT_SURFACE_ROW_ORDER = SOUTH_TO_NORTH

# Building rasters sampled at the cell centres of one measurement surface, which are the
# cell centres of the radio arrays on that surface. They take the terrain into account.
BUILDING_RASTERS_SUFFIX = "_buildings.npz"
BUILDING_MASK_DTYPE = "bool"
BUILDING_ROOF_DTYPE = "float32"

HEIGHT_MAP_DTYPE = "float32"
HEIGHT_MAP_VALUE = "roof_height_agl_m"
HEIGHT_MAP_ROW_ORDER = NORTH_TO_SOUTH
HEIGHT_MAP_NO_BUILDING = 0.0
MAX_HEIGHT_MAP_SIDE = 4096

# The height map, the voxels, the voxel depth and the receiver slice sample buildings at the
# cell centres of a north-up grid over the scene square, as the building mask and building
# rasters of the radio grid do.
SCENE_GRID_SAMPLE_LAYOUT = "cell_center"
VOXEL_VERTICAL_SAMPLING = (
    "level k lies at k * pitch_m and is solid when it lies within a building in the column: "
    "a native mesh measured above the ground under the cell centre, an extruded footprint "
    "from its nominal minimum height to its roof height"
)
VOXEL_DEPTH_DTYPE = "float32"
VOXEL_DEPTH_ROW_ORDER = NORTH_TO_SOUTH
VOXEL_DEPTH_NO_DATA = "NaN"

TERRAIN_AXIS_ORDER = ("south_to_north_row", "west_to_east_column")
TERRAIN_ELEVATION_SAMPLING = "nodes"
SURFACE_CLASS_SAMPLING = "cells"
SURFACE_CLASS_UNIT = "class_id"
SURFACE_CLASS_NAMES = MappingProxyType({str(int(item)): item.name.lower() for item in SurfaceClass})


[docs] def path_gain_packing() -> dict: """Return the location, data type and CF-style packing attributes of the path-gain array.""" return { "path": PATH_GAIN_ARRAY_PATH, "key": PATH_GAIN_KEY, "dtype": "uint16", "byte_order": "little", "units": PATH_GAIN_UNITS, "scale_factor": PATH_GAIN_SCALE_FACTOR, "add_offset": PATH_GAIN_ADD_OFFSET, "_FillValue": PATH_GAIN_FILL_VALUE, "valid_range": list(PATH_GAIN_VALID_RANGE), }
[docs] def conventions_record() -> dict: """Return the conventions block written into the dataset manifest.""" return { "column_order": WEST_TO_EAST, "horizontal_unit": LENGTH_UNIT, "height_reference": { "value": HEIGHT_REFERENCE, "applies_to": ["transmitter altitude_m", "receiver_height_m"], }, "cell_size": { "rule": "2 * radius_m / ceil(2 * radius_m / resolution_m)", "authoritative": "the absolute column_step_m and row_step_m recorded with each grid", }, "path_gain": { **path_gain_packing(), "axis_order": list(RADIO_ARRAY_AXIS_ORDER), "row_order": SOUTH_TO_NORTH, "packing": "round((10 * log10(path_gain) - add_offset) / scale_factor), half to even", "unpacking": "10 ** ((packed * scale_factor + add_offset) / 10)", "fill_value_meaning": "linear path gain 0: no simulated contribution", }, "derived": { "inputs": "the radio block of radio_map_info.json", "loader": "openworld_radio_twin.dataset.load_radio_map", "rss": { "unit": RADIO_METRIC_UNITS["rss"], "definition": "rss[i] = tx_power_w[i] * path_gain[i]", }, "sinr": { "unit": RADIO_METRIC_UNITS["sinr"], "definition": "sinr[i] = rss[i] / (sum over j != i of rss[j] + noise_power_w)", }, "association": { "dtype": ASSOCIATION_DTYPE, "unit": ASSOCIATION_UNIT, "axis_order": list(RADIO_ARRAY_AXIS_ORDER[1:]), "definition": ( "0-based index into request.transmitters of the largest value under " "association_metric; the first index wins a tie" ), "no_service": ASSOCIATION_NO_SERVICE, }, "no_coverage": 0.0, }, "images": { "written": "only with output.previews; never packaged", "row_order": IMAGE_ROW_ORDER, "units": dict(RADIO_IMAGE_UNITS), "no_data_rendering": IMAGE_NO_DATA_RENDERING, }, "measurement_surfaces": {"row_order": MEASUREMENT_SURFACE_ROW_ORDER}, "building_rasters": { "path": ( f"{SCENE_MEASUREMENT_SURFACES_DIRECTORY.as_posix()}/" f"<surface file stem>{BUILDING_RASTERS_SUFFIX}" ), "row_order": SOUTH_TO_NORTH, "grid": "the cell centres of the measurement surface and its radio arrays", "footprint_mask": {"dtype": BUILDING_MASK_DTYPE}, "roof_height_agl_m": { "dtype": BUILDING_ROOF_DTYPE, "unit": LENGTH_UNIT, "no_building": "NaN", }, "receiver_in_building_mask": {"dtype": BUILDING_MASK_DTYPE}, }, "height_map": { "path": SCENE_HEIGHT_MAP_PATH.as_posix(), "dtype": HEIGHT_MAP_DTYPE, "value": HEIGHT_MAP_VALUE, "unit": LENGTH_UNIT, "row_order": HEIGHT_MAP_ROW_ORDER, "no_building": HEIGHT_MAP_NO_BUILDING, "sample_layout": SCENE_GRID_SAMPLE_LAYOUT, "pixel_size": { "rule": f"2 * radius_m / min({MAX_HEIGHT_MAP_SIDE}, ceil(2 * radius_m))", "authoritative": "pixel_size_m recorded with the height map", }, }, "voxel_depth": { "dtype": VOXEL_DEPTH_DTYPE, "unit": LENGTH_UNIT, "row_order": VOXEL_DEPTH_ROW_ORDER, "no_data": VOXEL_DEPTH_NO_DATA, "sample_layout": SCENE_GRID_SAMPLE_LAYOUT, "cell_size": { "rule": "2 * radius_m / ceil(2 * radius_m / voxel_pitch_m)", "authoritative": "the grid block in vox_slices/ and vox_depth/scene_info.json", }, "vertical_sampling": VOXEL_VERTICAL_SAMPLING, }, "terrain": { "axis_order": list(TERRAIN_AXIS_ORDER), "elevation_sampling": TERRAIN_ELEVATION_SAMPLING, "elevation_unit": LENGTH_UNIT, "surface_class_sampling": SURFACE_CLASS_SAMPLING, "surface_classes": dict(SURFACE_CLASS_NAMES), }, }