Scene Geometry Assets

This page documents the geometry-related asset refs and bundle rules that Layer 7 storage implements. The storage layer owns persistence and worker-local resolution, while the scene composer and propagation layers consume the resolved refs.

External Tooling

Sionna RT consumes 3D scene assets, radio materials, transmitter and receiver positions, and antenna arrays, then computes radio paths. Mitsuba 3 provides the XML scene format and the mesh-loading substrate underneath Sionna RT [1, 2].

rfgen stores those inputs as typed asset refs and content-addressed bundles. It does not own OSM-to-Mitsuba conversion, ray-tracing algorithms, or antenna-pattern math in storage.

Typed Asset Kinds

Kind

Bundle write

Asset resolution

Notes

SIONNA_BUILTIN_SCENE

No, returned unchanged

sionna://builtin/<name>

The URI suffix names the shipped scene.

MITSUBA_XML_BUNDLE

Yes

local Path

XML entrypoint is validated, and relative filename, src, and href references must stay inside the bundle.

OPENGERT_MITSUBA_XML_BUNDLE

Yes

local Path

Same XML bundle rules as Mitsuba XML bundles.

MATERIAL_DB

Yes

local Path

Stored as a content-addressed bundle with a worker-local entrypoint.

ANTENNA_PATTERN

Yes

local Path

Stored as a content-addressed bundle with a worker-local entrypoint.

DEEPMIMO_EXPORT

Yes

local Path

Uses the same bundle machinery unless another layer adds extra semantics.

The bundle path and resolution rules are shared across all non-built-in kinds. XML-specific validation only applies to the two XML bundle kinds.

Bundle Layout

The store writes bundles under assets/<kind>/<content_hash>/. The manifest lives at manifest.cbor, and the payload files are written at their normalized relative paths under the same root.

The manifest fields are:

  • kind

  • content_hash

  • entrypoint

  • files[{path, sha256, size_bytes, media_type}]

  • source_uri

  • generator

  • generator_version

  • created_at_iso

  • license

The manifest is encoded with cbor2.dumps(manifest, canonical=True). The bundle hash is the SHA-256 of that canonical manifest plus each normalized relative path and payload, sorted by path. generator defaults to manual-mitsuba, and created_at_iso defaults to 1970-01-01T00:00:00+00:00 when the ref metadata omits them.

If entrypoint is absent on the input ref, storage uses the first normalized file path in sorted order. Duplicate paths after normalization are rejected, and bundle writes require at least one file.

The returned GeometryAssetRef preserves the input metadata, including version, media_type, and metadata, records the store URI, sets content_addressed=True, and carries the normalized entrypoint.

Validation And Resolution

Bundle paths must be relative and must stay inside the bundle root. Absolute paths, URIs, path traversal, and empty normalized paths are rejected.

XML bundles add one more check. The entrypoint file must exist in the bundle and parse as XML. For every XML attribute named filename, src, or href, storage resolves relative references against the entrypoint directory and requires the referenced file to be present in the bundle. Absolute and protocol-qualified references are ignored.

Asset resolution returns a Path for file-backed bundles and a URI string for built-in scenes. When worker_cache_dir is provided, storage resolves into <cache_root>/<kind>/<content_hash>/. After the first resolve, the sidecar .rfgen-resolved-asset.cbor records only the cached bundle entrypoint plus the per-file (path, size_bytes, sha256) metadata needed to validate a future hit. Every later worker-cache hit re-hashes the local cached files against those recorded SHA-256 values before reuse; a hash failure or missing file triggers a refresh from the asset store.

If the asset store is not local, asset resolution requires worker_cache_dir. Local file:// stores can resolve directly without a worker cache.

Worker Preparation

StoreHandle.prepare_worker_assets is the orchestration-facing helper. It resolves the scene-geometry ref, material-db ref, and antenna-pattern refs in a SceneAssetsConfig copy and replaces each file-backed ref with a worker-local entrypoint. Built-in scene refs stay as sionna://builtin/... URIs and are not rewritten to paths.

Authoring Paths

Sionna-shipped scenes are the low-friction starting point. For custom geometry, the supported path is usually Blender, OSM, CAD/BIM, or hand-authored Mitsuba XML exported into a bundle that matches the storage rules above. Storage does not convert those sources itself, it stores and resolves the exported bundle.

References

  1. NVIDIA Sionna RT documentation. https://nvlabs.github.io/sionna/rt/

  2. Mitsuba 3 documentation. Scene format. https://mitsuba.readthedocs.io/en/stable/src/key_topics/scene_format.html

  3. ITU-R Recommendation P.2040-3. Effects of building materials and structures on radiowave propagation above about 100 MHz. https://www.itu.int/rec/R-REC-P.2040/

  4. Hoydis, J. et al. Sionna RT: Differentiable Ray Tracing for Radio Propagation. https://nvlabs.github.io/sionna/rt/

  5. Tadik, S. et al. OpenGERT: Open Source Automated Geometry Extraction with Geometric and Electromagnetic Sensitivity Analyses for Ray-Tracing Propagation Models. https://arxiv.org/abs/2501.06945