OctreeCity

Voxel cities that stay small. OctreeCity stores a city as columns of label runs (ground up to 1 m, building up to 67 m, air above, tree canopy with air under it...). It builds adaptive octrees from them on demand, for any application: storage, ray analyses, machine learning, visualization, CFD.

All of Osaka: 556,724 buildings, 228 km² at 1 m, built in 26 s into one 37 MB file (a dense voxel grid would be 14.6 GB).

Why

Dense voxel grids (as in VoxCity) grow with volume: 1 m cells over a city is gigabytes, so people fall back to 5 m cells. City geometry is mostly vertical walls, flat roofs and layers, so OctreeCity stores runs along z. Size then follows the footprint outlines, not the volume.

What it does

Install

pip install octreecity              # core: storage, builders, analysis, exports
pip install "octreecity[viz]"       # + interactive 3D views and images
pip install "octreecity[notebook]"  # + JupyterLab, to run the tutorial notebook

From source: git clone https://github.com/MahmoudAbdelRahman/octreecity && cd octreecity && uv sync.

Start in one minute

from octreecity.easy import city_from_osm
from octreecity.analysis import street_points, sky_view_factor

city = city_from_osm(37.4979, 127.0276, size_m=800)   # any place: OSM buildings, land cover, trees, roads
pts, _ = street_points(city, every=2)
svf = sky_view_factor(city, pts)

Notebook: notebooks/octreecity_quickstart.ipynb (3D views, step by step). Full docs: quickstart, 3D views, inputs, analysis, octrees and adaptation, exports, whole cities, command line, file formats.

Run the notebook (and demo it without surprises)

cd octreecity
./demo.sh

demo.sh installs everything and opens the quickstart notebook in the project's own JupyterLab. That JupyterLab includes the plotly plugin, so the 3D views draw offline, without a "trust" step. In VS Code, open the notebook and choose the project's .venv kernel.

To avoid blank 3D views:

• Start Jupyter from the project (./demo.sh or uv run jupyter lab), not with uv run --with jupyterlab .... That starts JupyterLab from a separate environment without the plotly plugin.
• The notebook's first cell calls setup_notebook(). It also sends each view as a web page, so other front ends (classic Jupyter, nbviewer) still show it when online.
• Before a talk, run all cells once (Kernel > Restart and Run All, about 40 s). The OSM download is then cached in data/, and the demo works with no internet.
• Backup: a web-page version of the notebook can be built with uv run python scripts/notebook_report.py (writes outputs/report/quickstart_page.html).

Use with your own data

from octreecity.sources import read_citygml
from octreecity.builder import CityBuilder
from octreecity.analysis import street_points, sky_view_factor

bld = read_citygml("buildings.gml.gz").clip(x0, y0, x0 + 1000, y0 + 1000)
b = CityBuilder(x0, y0, 1000, 1000, cell=1.0)
b.add_terrain(dem)             # raster or callable(x, y), metres
b.add_buildings(bld)
city = b.build()               # ColumnCity
city.save("city.npz")

pts, _ = street_points(city, every=2)
svf = sky_view_factor(city, pts)
tree = city.to_octree(5)       # adaptive cells, 1 m to 32 m

Command line:

octreecity tiles --wkb-pickle buildings.pkl.gz --cell 1 -o city.ocz
octreecity info city.ocz
octreecity svf city.ocz --region 40 46 44 50 -o svf.png
octreecity sun city.npz --lat 34.69 --lon 135.5 --tz 9 --date 2026-12-21 -o sun.png
octreecity obj city.npz -o city.obj
octreecity foam city.npz --max-cell 16 --near 8 -o case/

All lengths are metres, in the projected CRS of the input data.

Status: alpha (0.1)

Works and is tested (56 tests, Python 3.10 to 3.13) on Osaka (PLATEAU) and Daejeon (V-World CityGML plus OpenStreetMap). Known gaps:

• No DEM reader yet. The KAIST demo estimates terrain from building base heights.
• The OpenFOAM export passes the package's own closedness and volume checks, but has not been run through OpenFOAM checkMesh yet. It takes about 24 s for 1.7 M cells (binary files).
• Ray analyses: direct sun and sky visibility only (no reflections or diffuse light), trees opaque, grid north taken as true north.
• The tiled builder takes buildings and land cover, not yet trees or terrain.
• File formats may still change before 1.0.

Data credits

Demo data, not included in the repository: PLATEAU (MLIT Japan) for Osaka, V-World (Korea) for Daejeon buildings, and © OpenStreetMap contributors (ODbL) for land cover, trees and roads in the KAIST images.

License

MIT, see LICENSE.