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)

Shared and derived assets#

The shared_assets entry of scene_info.json lists the files written at compilation, among them scene.xml, provenance.json, mesh/, source_buildings.json, the height map, and terrain/ when an environment grid was compiled. The same entry lists the products that depend on receiver settings: measurement surfaces for each (cell_size, height) pair, and voxel products for a pitch. rt.measurement_surface adds a surface on demand; compile_scene writes one surface and the voxel products up front, and a dataset writes those its radio maps need.

A compiled scene’s scene_info.json also has status: compiled and a derived_assets block that says whether the measurement surfaces and voxels are complete; its provenance is the compilation block below. A dataset scene’s scene_info.json has no derived_assets; it has the generation status, the radio_maps counts, and a provenance summary of its buildings, terrain and surfaces, and of its antennas when it takes transmitters from them (Dataset layout).

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 scene z refers to modelled terrain at the origin or to the z = 0 plane.

  • 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 one rt.load_scene uses for the same geometry inputs.

  • building_assets and local_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.