Scene layout#
Every compiled scene, whether from the loader cache, the CLI or a dataset, uses one layout.
The constants live in openworld_radio_twin.scene_format.
<scene>/
|-- scene_info.json specification, provenance summary, asset lists
|-- scene.xml Mitsuba / Sionna RT scene referencing the meshes
|-- provenance.json coordinate, geometry, material and bounds records
|-- source_buildings.json building records, source selection, licence and credit
|-- source_antennas.json antenna records a dataset scene takes transmitters from
|-- antennas/ antenna selections placed in the scene (rt.antennas, explorer)
|-- 2D_Building_Height_Map.npy north-up building height raster
|-- mesh/ binary PLY: buildings, ground, vegetation, paved, fresh and
| sea water
|-- terrain/
| |-- source_elevation_m.npy
| |-- model_elevation_m.npy
| |-- local_elevation_m.npy
| |-- surface_classes.npy
| `-- scene_info.json axes, datum, source resolution, class and material mappings,
| provider warnings
|-- measurement_surfaces/ terrain-following receiver meshes keyed by cell size and AGL,
| with building rasters in dataset scenes
|-- vox_slices/ sparse voxels and receiver-height occupancy
|-- vox_depth/ maximum-z arrays, 16-bit depth PNG, preview, metadata
`-- radio_maps/ radio maps (dataset scenes only)
Height map and voxel grids#
The height map, the voxels, the voxel depth and the receiver slice sample buildings at cell
centres, as the building mask and building rasters of the radio grid do. Each covers the scene
square with a north-up grid of size x size cells of side 2 * radius_m / size, where size
is ceil(2 * radius_m / voxel_pitch_m) for the voxel products and
min(4096, ceil(2 * radius_m)) for the height map. A native mesh fills the cells whose
centre lies under its shell, and an extruded footprint the cells whose centre lies inside it
(not on its outline).
Heights keep the vertical rule of each building form. A native mesh is placed at its terrain anchor, as in the scene mesh, and measured above the ground under each cell centre, so on sloped ground its roof lies lower where the ground rises. An extruded footprint spans its nominal base and roof heights in every cell it fills.
points_xyz in vox_slices/scene_voxels_pitch<pitch>.npz holds one row per solid voxel: the
east and north of its cell centre, and its level k * voxel_pitch_m. A voxel is solid when
its level lies within a building in that cell. k is negative where a native mesh reaches
below the ground under the cell, for example on a slope; the fifth value of bbox gives the
lowest level. The depth array holds the highest solid level of each cell, and the receiver
slice tests the receiver height itself. The vox_slices/scene_info.json and
vox_depth/scene_info.json files carry the same grid block: the shape, the first
(north-west) cell centre, the steps and this vertical rule. height_map.pixel_size_m in
vox_slices/scene_info.json records the height map’s cell size.
The 16-bit depth PNG maps each depth linearly onto codes 1 to 65535 between
minimum_depth_m and maximum_depth_m of its png_encoding, a range that always holds 0.
Code 0 marks cells without a solid voxel, and decode gives the inverse:
depth_m = minimum_depth_m + (code - 1) * metres_per_code. The preview colours the same range.
Provenance contents#
provenance.json records the scene’s conventions:
scene_layout: layout format, version and the relative paths of the scene files.coordinate_contract: EPSG:4326 input, topocentric ENU frame, origin, axis order, units, the terrain source datum, and whether scenezrefers to modelled terrain at the origin or to thez = 0plane.geometry_contract: the building footing rule and margin, and the boundary policy (complete footprints within the square ENU bounds).material_contract: profile name and version, and the terrain layer thickness.bounds: radius, local envelope and WGS84 corners.compilation: compiler version, the geometry request with its resolved building source, cache key, building provider and release, source, excluded and exported building counts, the scene boundary policy, and the building and environment warnings. Compiled and dataset scenes both carry it; the cache key is the onert.load_sceneuses for the same geometry inputs.building_assetsandlocal_buildings: per-building triangle counts and placement.
Source records#
source_buildings.json holds the building source’s provider name, release, license,
license_url and attribution, its warnings, the count of footprints excluded at the
boundary, the resolved source selection, and one record per building. An Overture record
keeps its GERS ID and the first upstream record ID. The source_datasets list gives each
upstream dataset that the fetched Overture records name, with its licence and the number of
records naming it; the count includes records later dropped at the scene boundary.
terrain/scene_info.json keeps the terrain source with its license, license_url and
attribution, and the surface source with the Overture licence and credit and the upstream
datasets it names.
Version markers#
The scene cache key combines the geometry request with the compiler version, the scene layout version, the building mesh schema version, the scene format name, a geometry revision and the RF material profile version. A change to any of them produces a new cache directory. Dataset resume requires the software version that created the dataset, which fixes all of them.
The scene layout is version 2 and the RF material profile is version 3 (Surfaces and materials).
Reusing a scene at an explicit output path that records another layout or profile version
fails with a message to compile it again with if_exists="replace". The web service
refuses to open a cached scene by its ID when the scene records another profile version.
The schema_version in a compiled scene’s scene_info.json equals the scene layout version.
A dataset scene’s scene_info.json carries the dataset format version instead.