VoxCity: open geospatial data turned into a voxel city model you can simulate

Two modules, one grid

VoxCity is a Python framework for integrating geospatial data, 3D city modeling and urban simulation, and the tagline says what it does: generate grid-based 3D city models anywhere on Earth from open geospatial data, then simulate solar, view and microclimate.

The architecture is two modules with a clean boundary. The generator module downloads building heights, tree canopy heights, land cover and terrain elevation for a target area and voxelizes them into an integrated voxel city model. The simulator module runs environmental analyses such as solar radiation and view index on that model.

The five reasons given for using it are worth reading as a specification. Global by default, because it automatically selects the best open data source for any location worldwide. One integrated voxel model, with buildings, trees, land cover and terrain fused into a single semantic 3D grid. Built-in simulation of solar irradiance, sky and green view index, landmark visibility and network analysis. Export anywhere, to ENVI-met in INX and EDB formats, to PALM through the NetCDF static driver, to OBJ for Blender, Rhino and Twinmotion, and to MagicaVoxel as VOX. And reproducible and open, with open data and documented provenance and a peer-reviewed method.

That last point is the one that separates it from a demo. A voxel model of a city assembled from several open sources is only useful if you know which source produced which building, and the project treats that as a feature.

The project is MIT licensed, the primary language is Python, the homepage is the readthedocs site, and the last push was on 2026-10-05. The package version in the manifest is 1.7.0, and the project publishes no GitHub releases, so the PyPI version and the repository are the version story.

The quick start is a rectangle and a mesh size

The Quick Start section is short enough to read in one go, and it shows the shape of the API.

import ee
from voxcity.generator import get_voxcity

ee.Initialize(project="your-project-id")

# A ~450 m box in Seattle (lon, lat corners)
rectangle_vertices = [
    (-122.3359, 47.5983), (-122.3359, 47.6028),
    (-122.3292, 47.6028), (-122.3292, 47.5983),
]

# Auto-selects the best data sources for the location
voxcity = get_voxcity(rectangle_vertices, meshsize=5)

The rectangle is four longitude and latitude corners, and the comment notes it is a box of about 450 metres in Seattle. The mesh size is 5, which is the voxel edge in metres, so the same call at meshsize=1 would produce a model twenty-five times finer in each dimension.

Two things stand out. Earth Engine is initialised first, with a project id, so the framework is reaching out to Google Earth Engine before it does anything else, which tells you that a substantial part of the data pipeline runs through it. And the source selection is automatic, with the comment saying it auto-selects the best data sources for the location, which is the answer to the question you would otherwise have to ask first.

There is also a Colab demo linked, so the whole pipeline can be run in a browser before you install anything locally, and a YouTube walkthrough.

Installation is GDAL through conda, then a pip package

Make sure you have Python 3.10 to 3.13 installed. GDAL is the one dependency best installed via conda, and everything else comes from pip. The local environment recipe is:

conda create --name voxcity python=3.12
conda activate voxcity
conda install -c conda-forge gdal timezonefinder
pip install voxcity

The recommendation to install GDAL through conda rather than pip is the kind of detail that saves an afternoon, since GDAL has compiled dependencies and a long history of being awkward to install from source.

The quick start install is the same package with a note about the extra setup:

pip install voxcity   # see Installation for GDAL + Earth Engine setup

And for Google Colab it is a single line in a notebook cell:

!pip install voxcity

The Earth Engine setup is a separate step because many data sources are served through it. You set up an Earth Engine enabled Cloud Project by following the official guide, then authenticate:

# Local environment
earthengine authenticate

and in Colab you click the displayed link, generate a token and paste it back:

# Google Colab: click the displayed link, generate a token, then paste it
!earthengine authenticate --auth_mode=notebook

The Colab variant uses a different auth mode flag, which is a small but essential difference: the notebook mode prints a link instead of trying to open a local browser.

The dependency list explains what the pipeline actually does

The pyproject manifest lists more than fifty dependencies, and reading them tells you what the framework is made of.

The geospatial core is rasterio, geopandas, shapely, fiona, pyproj and rtree, with affine and xarray for the array side and netCDF4 for the NetCDF outputs that PALM consumes. numpy, scipy, pandas and scikit-learn do the numeric work. py-vox-io handles the MagicaVoxel VOX format, ezdxf for DXF export, trimesh and pyvista for the 3D geometry and visualisation, and h5py for the file formats the framework reads and writes.

Then there are the things that show the domain. earthengine-api and geemap for the Google side, osmnx for OpenStreetMap extraction, overturemaps for the newer building footprint dataset, geopy for reverse geocoding, reverse_geocoder and pycountry for place names, timezonefinder and astral for timezone and solar position calculation, and contextily for basemap tiles.

The optional extra is the interesting one. taichi is marked as an optional dependency and there is a gpu extra that enables it, plus a separate gpu dependency group, so the simulation can run on a GPU without forcing that dependency on everyone else.

The rest of the tooling is conventional: poetry for the build, pytest for tests with pytest-benchmark and a bench/ directory, mypy and ruff for typing and linting, tox for multi-version testing, and FastAPI with httpx and python-multipart in the dev group, which is the web application that the Docker compose file and the .env.example configuration point at.

The environment file shows a container deployment with real data paths

The .env.example is more informative than a typical example file, because it documents the deployment rather than just the variables.

You copy it to .env, which is untracked, and adjust it for your machine, and real environment variables always override these. The base data directory defaults to app/data when unset, and there is an absolute path to the PLATEAU CityGML dataset directory, with the example pointing at a Tokyo ward dataset.

Then there is a second block, the Linux and Docker example, with the comment that these are read by docker-compose.yml itself for variable substitution, so you set them in a repo-root .env rather than .env.docker if you need non-default values. The variables are the host port, the host root directory, the host ocean cache directory, and the CityGML path inside the container.

The comment on the data and output directories explains the defaults: VOXCITY_DATA_DIR and VOXCITY_OUTPUT_DIR default to /work-voxcity/data and /work-voxcity/output inside the container, baked into the Dockerfile, and do not normally need overriding, because the docker-compose bind mount is what actually populates them with real data. That is a useful distinction, because it means the bind mount is the mechanism and the variables are the fallback.

The optional overrides are the cityGML path, the default Tokyo EPW weather file, and an NDSM cog path, and the session and runtime block holds the maximum upload size, the host root, the ocean cache and the Earth Engine project.

Simulation outputs and where they go

The gallery in the README shows the range of outputs, and the captions are the clearest inventory of what the simulator module produces. There is solar irradiance, the sky and green view index, an ENVI-met microclimate image, an OBJ rendering in Rhino and Blender, a MagicaVoxel file, and a network analysis view.

That matches the Why section, which lists the built-in simulation as solar irradiance, sky and green view index, landmark visibility and network analysis, and the export list as ENVI-met with the INX and EDB formats, PALM through the NetCDF static driver, OBJ for Blender, Rhino and Twinmotion, and MagicaVoxel as VOX.

The ENVI-met and PALM exports are the ones that matter most for the stated purpose, because those are the inputs that CFD software expects. A voxel grid is a convenient intermediate representation for the simulation, but the tools that do the actual microclimate modelling want their own formats, and a framework that writes both means the model is not locked to its own viewer.

The OBJ export serves a different audience, the visualisation and modelling side, and the MagicaVoxel export is for the voxel art and game engine route, which is also where the VOX format in the dependency list comes from.

The whole thing is documented on readthedocs, there is a paper linked with a DOI in the badge row, and the project credits are in their own section. The repository layout backs the split up, with src/ for the package, tests/ and bench/ for the test and benchmark suites, scripts/ for the demo reel generation, and a Makefile whose targets cover cleaning, linting, tests, coverage and docs.

Editorial conclusion

Adopt VoxCity if you need a reproducible 3D model of a real place for microclimate or solar work and you want the data provenance to be documented, and you are prepared to set up GDAL, Earth Engine and a large dependency set. Do not adopt it for a quick visualisation, because the pipeline pulls building footprints and terrain from several sources and the install is heavy. Before you start, set up an Earth Engine enabled Cloud Project and authenticate, since many of the data sources are served through it, and install GDAL through conda rather than pip, which the README recommends.

Frequently asked questions

Official sources

1. Issues
2. kunifujiwara/VoxCity on GitHub
3. License: MIT
4. Project website
5. README