voxelcity is an easy and one-stop tool to output 3d city models for microclimate simulation by integrating multiple geospatial open-data
VoxelCity is a Python package that facilitates the creation of voxel-based 3D urban environments and related geospatial analyses. It integrates various geospatial datasets—such as building footprints, land cover, canopy height, and digital elevation models (DEMs)—to generate 2D and 3D representations of urban areas. It can export data in formats compatible with popular simulation tools like ENVI-MET, as well as visualization tools like MagicaVoxel, and supports simulations such as sky view index and green view index calculations.
Integration of Multiple Data Sources:
Combines building footprints, land cover data, canopy height maps, and DEMs to generate a consistent 3D voxel representation of an urban scene.
Flexible Input Sources:
Supports various building and terrain data sources including:
Detailed information about each data source can be found in the References of Data Sources section.
Customizable Domain and Resolution:
Easily define a target area by drawing a rectangle on a map or specifying center coordinates and dimensions. Adjust the mesh size to meet resolution needs.
Integration with Earth Engine:
Leverages Google Earth Engine for large-scale geospatial data processing (authentication and project setup required).
Output Formats:
Analytical Tools:
Make sure you have Python 3.12 installed. Install VoxelCity with:
conda create --name voxelcity python=3.12
conda activate voxelcity
conda install -c conda-forge gdal
pip install voxelcity
!pip install voxelcity
To use Earth Engine data, set up your Earth Engine enabled Cloud Project by following the instructions here: https://developers.google.com/earth-engine/cloud/earthengine_cloud_project_setup
After setting up, authenticate and initialize Earth Engine:
earthengine authenticate
# Click displayed link, generate token, copy and paste the token
!earthengine authenticate --auth_mode=notebook
import ee
ee.Authenticate()
ee.Initialize(project='your-project-id')
You can define your target area in three ways:
Define the target area by directly specifying the coordinates of the rectangle vertices.
rectangle_vertices = [
(47.59830044521263, -122.33587348582083), # Southwest corner (latitude, longitude)
(47.60279755390168, -122.33587348582083), # Northwest corner (latitude, longitude)
(47.60279755390168, -122.32922451417917), # Northeast corner (latitude, longitude)
(47.59830044521263, -122.32922451417917) # Southeast corner (latitude, longitude)
]
Use the GUI map interface to draw a rectangular domain of interest.
from voxelcity.geo.draw import draw_rectangle_map_cityname
cityname = "tokyo"
m, rectangle_vertices = draw_rectangle_map_cityname(cityname, zoom=15)
m
Choose the width and height in meters and select the center point on the map.
from voxelcity.geo.draw import center_location_map_cityname
width = 500
height = 500
m, rectangle_vertices = center_location_map_cityname(cityname, width, height, zoom=15)
m
Define data sources and mesh size (m):
building_source = 'OpenStreetMap' # Building footprint and height data source
land_cover_source = 'OpenStreetMap' # Land cover classification data source
canopy_height_source = 'High Resolution 1m Global Canopy Height Maps' # Tree canopy height data source
dem_source = 'DeltaDTM' # Digital elevation model data source
meshsize = 5 # Grid cell size in meters
kwargs = {
"output_dir": "output", # Directory to save output files
"dem_interpolation": True # Enable DEM interpolation
}
Generate voxel data grids and corresponding building geoJSON:
from voxelcity import get_voxelcity
voxelcity_grid, building_height_grid, building_min_height_grid, \
building_id_grid, canopy_height_grid, land_cover_grid, dem_grid, \
building_geojson = get_voxelcity(
rectangle_vertices,
building_source,
land_cover_source,
canopy_height_source,
dem_source,
meshsize,
**kwargs
)
ENVI-MET is an advanced microclimate simulation software specialized in modeling urban environments. It simulates the interactions between buildings, vegetation, and various climate parameters like temperature, wind flow, humidity, and radiation. The software is used widely in urban planning, architecture, and environmental studies (Commercial, offers educational licenses).
from voxelcity.file.envimet import export_inx, generate_edb_file
envimet_kwargs = {
"output_directory": "output", # Directory where output files will be saved
"author_name": "your name", # Name of the model author
"model_description": "generated with VoxelCity", # Description text for the model
"domain_building_max_height_ratio": 2, # Maximum ratio between domain height and tallest building height
"useTelescoping_grid": True, # Enable telescoping grid for better computational efficiency
"verticalStretch": 20, # Vertical grid stretching factor (%)
"min_grids_Z": 20, # Minimum number of vertical grid cells
"lad": 1.0 # Leaf Area Density (m2/m3) for vegetation modeling
}
export_inx(building_height_grid, building_id_grid, canopy_height_grid, land_cover_grid, dem_grid, meshsize, land_cover_source, rectangle_vertices, **envimet_kwargs)
generate_edb_file(**envimet_kwargs)
Example Output Exported in INX and Inported in ENVI-met
from voxelcity.file.obj import export_obj
output_directory = "output" # Directory where output files will be saved
output_file_name = "voxcity" # Base name for the output OBJ file
export_obj(voxelcity_grid, output_directory, output_file_name, meshsize)
The generated OBJ files can be opened and rendered in the following 3D visualization software:
Example Output Exported in OBJ and Rendered in MagicaVoxel
MagicaVoxel is a lightweight and user-friendly voxel art editor. It allows users to create, edit, and render voxel-based 3D models with an intuitive interface, making it perfect for modifying and visualizing voxelized city models. The software is free and available for Windows and Mac.
from voxelcity.file.magicavoxel import export_magicavoxel_vox
output_path = "output"
base_filename = "voxelcity"
export_magicavoxel_vox(voxelcity_grid, output_path, base_filename=base_filename)
Example Output Exported in VOX and Rendered in MagicaVoxel
from voxelcity.sim.view import get_green_view_index, get_sky_view_index
# Dictionary of parameters for view index analysis
view_kwargs = {
"view_point_height": 1.5, # Height of observer viewpoint in meters
"dem_grid": dem_grid, # Digital elevation model grid
"colormap": "viridis", # Colormap for visualization
"obj_export": True, # Whether to export as OBJ file
"output_directory": "output", # Directory to save output files
"output_file_name": "gvi" # Base filename for outputs
}
gvi_grid = get_green_view_index(voxelcity_grid, meshsize, **view_kwargs)
view_kwargs["colormap"] = "BuPu_r"
view_kwargs["output_file_name"] = "svi"
svi_grid = get_sky_view_index(voxelcity_grid, meshsize, **view_kwargs)
Example Results Saved as OBJ and Rendered in Rhino
from voxelcity.sim.view import get_landmark_visibility_map
# Dictionary of parameters for landmark visibility analysis
landmark_kwargs = {
"view_point_height": 1.5, # Height of observer viewpoint in meters
"rectangle_vertices": rectangle_vertices, # Vertices defining simulation domain boundary
"dem_grid": dem_grid, # Digital elevation model grid
"colormap": "cool", # Colormap for visualization
"obj_export": True, # Whether to export as OBJ file
"output_directory": "output", # Directory to save output files
"output_file_name": "landmark_visibility" # Base filename for outputs
}
landmark_vis_map = get_landmark_visibility_map(voxelcity_grid, building_id_grid, building_geojson, meshsize, **landmark_kwargs)
Example Result Saved as OBJ and Rendered in Rhino
| Dataset | Spatial Coverage | Source/Data Acquisition |
|---|---|---|
| OpenStreetMap | Worldwide (24% completeness in city centers) | Volunteered / updated continuously |
| Global ML Building Footprints | North America, Europe, Australia | Prediction from satellite or aerial imagery / 2018-2019 for majority of the input imagery |
| Open Buildings 2.5D Temporal Dataset | Africa, Latin America, and South and Southeast Asia | Prediction from satellite imagery / 2016-2023 |
| EUBUCCO v0.1 | 27 EU countries and Switzerland (378 regions and 40,829 cities) | OpenStreetMap, government datasets / 2003-2021 (majority is after 2019) |
| UT-GLOBUS | Worldwide (more than 1200 cities or locales) | Prediction from building footprints, population, spaceborne nDSM / not provided |
| Overture Maps | Worldwide | OpenStreetMap, Esri Community Maps Program, Google Open Buildings, etc. / updated continuously |
| Dataset | Coverage | Resolution | Source/Data Acquisition |
|---|---|---|---|
| High Resolution 1m Global Canopy Height Maps | Worldwide | 1 m | Prediction from satellite imagery / 2009 and 2020 (80% are 2018-2020) |
| ETH Global Sentinel-2 10m Canopy Height (2020) | Worldwide | 10 m | Prediction from satellite imagery / 2020 |
| Dataset | Spatial Coverage | Resolution | Source/Data Acquisition |
|---|---|---|---|
| ESA World Cover 10m 2021 V200 | Worldwide | 10 m | Prediction from satellite imagery / 2021 |
| ESRI 10m Annual Land Cover (2017-2023) | Worldwide | 10 m | Prediction from satellite imagery / 2017-2023 |
| Dynamic World V1 | Worldwide | 10 m | Prediction from satellite imagery / updated continuously |
| OpenStreetMap | Worldwide | - (Vector) | Volunteered / updated continuously |
| OpenEarthMap Japan | Japan | ~1 m | Prediction from aerial imagery / 1974-2022 (mostly after 2018 in major cities) |
| UrbanWatch | 22 major cities in the US | 1 m | Prediction from aerial imagery / 2014–2017 |
| Dataset | Coverage | Resolution | Source/Data Acquisition |
|---|---|---|---|
| FABDEM | Worldwide | 30 m | Correction of Copernicus DEM using canopy height and building footprints data / 2011-2015 (Copernicus DEM) |
| DeltaDTM | Worldwide (Only for coastal areas below 10m + mean sea level) | 30 m | Copernicus DEM, spaceborne LiDAR / 2011-2015 (Copernicus DEM) |
| USGS 3DEP 1m DEM | United States | 1 m | Aerial LiDAR / 2004-2024 (mostly after 2015) |
| England 1m Composite DTM | England | 1 m | Aerial LiDAR / 2000-2022 |
| Australian 5M DEM | Australia | 5 m | Aerial LiDAR / 2001-2015 |
| RGE Alti | France | 1 m | Aerial LiDAR |
Please cite the paper if you use voxelcity in a scientific publication:
Fujiwara, K., XXX. XXX. XXX, XXX, XXX.
@article{,
author = {Fujiwara, Kunihiko and XXX, XXX and XXX, XXX and XXX, XXX},
doi = {XXX},
journal = {XXX},
pages = {XXX},
title = {XXX},
volume = {XXX},
year = {XXX}
}
This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.
FAQs
voxelcity is an easy and one-stop tool to output 3d city models for microclimate simulation by integrating multiple geospatial open-data
We found that voxelcity demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.