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, shared and derived assets
|-- scene.xml                    Mitsuba / Sionna RT scene referencing the meshes
|-- provenance.json              coordinate, geometry, material and bounds contracts
|-- source_buildings.json        provider records as received, with attributes and licences
|-- 2D_Building_Height_Map.npy   north-up building height raster
|-- mesh/                        binary PLY: buildings, ground, vegetation, paved, 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
|-- measurement_surfaces/        terrain-following receiver meshes keyed by cell size and AGL
|-- vox_slices/                  sparse voxels and receiver-height occupancy
|-- vox_depth/                   maximum-z arrays, 16-bit depth PNG, preview, metadata
`-- cases/                       dataset cases (datasets only)

Shared and derived assets#

scene_info.json distinguishes shared assets, written at compilation, from derived assets that depend on solver settings:

  • Shared: scene.xml, provenance.json, mesh/, source_buildings.json, the height map, and terrain/ when an environment grid was compiled.

  • Derived: measurement surfaces for each (cell_size, height) pair, and voxel products for a pitch. The loader adds them on demand; compile_scene and datasets write them up front.

Provenance contents#

provenance.json records the contracts that every consumer of the scene relies on:

  • 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.

  • bounds: radius, local envelope and WGS84 corners.

  • compilation: compiler version, the full request, cache key, building provider and release, source, excluded and exported building counts, and warnings.

  • building_assets and local_buildings: per-building triangle counts and placement.

Version markers#

Three markers are combined into the scene cache key and checked during dataset resume: the compiler version, the scene layout version, and the building mesh schema version. Any change to one of them produces a new cache directory rather than a silently different scene under an old name.