"""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),
},
}