Development#

Environment and checks#

./scripts/setup.sh
conda activate owrt
ruff check .
pytest
OWRT_RELOAD=1 ./scripts/run.sh

Unit and API tests use synthetic inputs and do not require network access.

scripts/benchmarks/ times scene compilation from the records of a cached scene, the provider queries behind one scene, and a cold load_scene. Scene compile performance records what the compile path costs and where the time went.

The browser screenshot check is optional and downloads Chromium outside the repository:

python -m pip install -e '.[ui-test]'
PLAYWRIGHT_BROWSERS_PATH=/tmp/owrt-playwright playwright install chromium
PLAYWRIGHT_BROWSERS_PATH=/tmp/owrt-playwright python scripts/check_ui.py

Repository map#

src/openworld_radio_twin/
|-- rt.py              Sionna-compatible loader and geographic helpers
|-- compiler.py        Scene compilation and cache
|-- dataset.py         Python dataset interface
|-- batch.py           Request schema, seeded expansion, generation and resume
|-- models.py          Simulation request and response models
|-- geodesy.py         WGS84 to ENU frame
|-- environment.py     Terrain grid, surface classes, material profiles
|-- scene_format.py    Canonical scene paths
|-- artifacts.py       Bundle export
|-- providers/         Overture, OSM, 3DBAG, Berlin, Boston, terrain, surfaces
|-- simulation/        Scene builder, Sionna adapter, preview, radio-map contract
|-- main.py            FastAPI application
|-- cli.py             `owrt` command
`-- web/               Explorer and batch pages
tests/                 Unit and API tests
examples/              Notebooks, dataset script, Slurm job, plugin example
docs/                  This documentation
website/               Project page

Building the documentation#

python -m pip install -e '.[docs]'
cd docs
make html            # output in docs/_build/html

The build runs with warnings as errors. Notebooks are rendered from their committed outputs and are not executed. make livehtml starts a rebuilding preview when sphinx-autobuild is installed.

The GitHub Actions workflow in .github/workflows/pages.yml publishes the project page and this documentation to GitHub Pages on every push to main: the page at the site root and the documentation under /docs/.

Conventions#

  • Public behaviour is described only when it exists in the code and is covered by a test.

  • Geometry-affecting changes bump the scene layout, mesh schema or compiler version so cached scenes and resumable datasets never change silently.

  • Provider responses stay in memory; nothing from a provider is committed to the repository.