VoxCity

You can define your target area in two ways:

Option 1: Direct Coordinate Input

Define the target area by directly specifying the coordinates of the rectangle vertices.

rectangle_vertices = [
    (-122.33587348582083, 47.59830044521263),  # Southwest corner (longitude, latitude)
    (-122.33587348582083, 47.60279755390168),  # Northwest corner (longitude, latitude) 
    (-122.32922451417917, 47.60279755390168),  # Northeast corner (longitude, latitude)
    (-122.32922451417917, 47.59830044521263)   # Southeast corner (longitude, latitude)
]

Option 2: Draw on a Map (for Jupyter Notebook)

One map with a side panel: type a city, then draw an aligned or rotated box, or click Fixed and click a centre point to place a box of the given width and height (metres).

from voxcity.geoprocessor.draw import create_rectangle_map

m, rectangle_vertices = create_rectangle_map("tokyo", zoom=15, width=500, height=500)
m

draw_rectangle_map_cityname and center_location_map_cityname still work for drawing only a free box or only a fixed-size box.

Importing Rhino Models (OBJ):

You can import buildings authored in Rhino into a VoxCity model:

from voxcity.importer import add_buildings_from_obj

voxcity = add_buildings_from_obj(
    voxcity, "design.obj",
    anchor_lonlat=(139.7536, 35.6841),  # world (lon, lat) of the model anchor
    anchor_elevation=12.0,              # world elevation (m) of the anchor
    rotation=0.0, units="m",
)

See docs/guides/rhino_obj_import.md for the full Rhino export guide.

Building a model from CityGML:

from voxcity.generator import get_voxcity_CityGML

voxcity = get_voxcity_CityGML(
    rectangle_vertices,
    land_cover_source='OpenStreetMap',
    canopy_height_source='High Resolution 1m Global Canopy Height Maps v2',
    meshsize=meshsize,
    citygml_path="path/to/citygml_folder",   # or url_citygml="https://..." for a PLATEAU zip
)

See the VoxCityGML repository and its paper for LOD2 workflows.

Compute Solar Irradiance:

from voxcity.simulator.solar import get_global_solar_irradiance_using_epw

solar_kwargs = {
    "download_nearest_epw": True,  # Whether to automatically download nearest EPW weather file based on location from Climate.OneBuilding.Org
    # "epw_file_path": "./output/new.york-downtown.manhattan.heli_ny_usa_1.epw",  # Path to EnergyPlus Weather (EPW) file containing climate data. Set if you already have an EPW file.
    "calc_time": "01-01 12:00:00",  # Time for instantaneous calculation in format "MM-DD HH:MM:SS"
    "view_point_height": 1.5,  # Height of view point in meters for calculating solar access. Default: 1.5 m
    "tree_k": 0.6,    # Static extinction coefficient - controls how much sunlight is blocked by trees (higher = more blocking)
    "tree_lad": 1.0,    # Leaf area density of trees - density of leaves/branches that affect shading (higher = denser foliage)
    "colormap": 'magma',       # Matplotlib colormap for visualization. Default: 'viridis'
    "obj_export": True,        # Whether to export results as 3D OBJ file
    "output_directory": 'output/test',  # Directory for saving output files
    "output_file_name": 'instantaneous_solar_irradiance',  # Base filename for outputs (without extension)
    "alpha": 1.0,             # Transparency of visualization (0.0-1.0)
    "vmin": 0,               # Minimum value for colormap scaling in visualization
    # "vmax": 900,             # Maximum value for colormap scaling in visualization
}

# Compute global solar irradiance map (direct + diffuse radiation)
solar_grid = get_global_solar_irradiance_using_epw(
    voxcity,                             # VoxCity object containing voxel data and metadata
    calc_type='instantaneous',           # Calculate instantaneous irradiance at specified time
    direct_normal_irradiance_scaling=1.0, # Scaling factor for direct solar radiation (1.0 = no scaling)
    diffuse_irradiance_scaling=1.0,      # Scaling factor for diffuse solar radiation (1.0 = no scaling)
    **solar_kwargs                       # Pass all the parameters defined above
)

# Adjust parameters for cumulative calculation
solar_kwargs["start_time"] = "01-01 01:00:00" # Start time for cumulative calculation
solar_kwargs["end_time"] = "01-31 23:00:00" # End time for cumulative calculation
solar_kwargs["output_file_name"] = 'cumulative_solar_irradiance'  # Base filename for outputs (without extension)

# Calculate cumulative solar irradiance over the specified time period
cum_solar_grid = get_global_solar_irradiance_using_epw(
    voxcity,                             # VoxCity object containing voxel data and metadata
    calc_type='cumulative',              # Calculate cumulative irradiance over time period instead of instantaneous
    direct_normal_irradiance_scaling=1.0, # Scaling factor for direct solar radiation (1.0 = no scaling)
    diffuse_irradiance_scaling=1.0,      # Scaling factor for diffuse solar radiation (1.0 = no scaling)
    **solar_kwargs                       # Pass all the parameters defined above
)

Example Results Saved as OBJ and Rendered in Rhino

Compute Green View Index (GVI) and Sky View Index (SVI):

from voxcity.simulator.view import get_view_index

view_kwargs = {
    "view_point_height": 1.5,      # Height of observer viewpoint in meters
    "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
}

# Compute Green View Index using mode='green'
gvi_grid = get_view_index(voxcity, mode='green', **view_kwargs)

# Adjust parameters for Sky View Index
view_kwargs["colormap"] = "BuPu_r"
view_kwargs["output_file_name"] = "svi"
view_kwargs["elevation_min_degrees"] = 0 # Start ray-tracing from the horizon

# Compute Sky View Index using mode='sky'
svi_grid = get_view_index(voxcity, mode='sky', **view_kwargs)

Example Results Saved as OBJ and Rendered in Rhino

Landmark Visibility Map:

from voxcity.simulator.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
    "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(voxcity, voxcity.extras.get('building_gdf'), **landmark_kwargs)

Example Result Saved as OBJ and Rendered in Rhino

Network Analysis:

from voxcity.geoprocessor.network import get_network_values

network_kwargs = {
    "network_type": "walk",        # Type of network to download from OSM (walk, drive, all, etc.)
    "colormap": "magma",          # Matplotlib colormap for visualization
    "vis_graph": True,            # Whether to display the network visualization
    "vmin": 0.0,                  # Minimum value for color scaling
    "vmax": 600000,               # Maximum value for color scaling
    "edge_width": 2,              # Width of network edges in visualization
    "alpha": 0.8,                 # Transparency of network edges
    "zoom": 16                    # Zoom level for basemap
}

G, edge_gdf = get_network_values(
    cum_solar_grid,               # Grid of cumulative solar irradiance values
    rectangle_vertices,           # Coordinates defining simulation domain boundary
    meshsize,                     # Size of each grid cell in meters
    value_name='Cumulative Global Solar Irradiance (W/m²·hour)',  # Label for values in visualization
    **network_kwargs              # Additional visualization and network parameters
)

Cumulative Global Solar Irradiance (kW/m²·hour) on Road Network

ENVI-MET INX/EDB Files:

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 voxcity.exporter.envimet import export_inx, generate_edb_file

envimet_kwargs = {
    "output_directory": "output",            # Directory where output files will be saved
    "file_basename": "voxcity",              # Base name (without extension) for INX
    "author_name": "your name",              # Name of the model author
    "model_description": "generated with voxcity",  # Description for the model
    "domain_building_max_height_ratio": 2,   # Max ratio between domain height and tallest building
    "useTelescoping_grid": True,             # Enable telescoping grid
    "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 EDB generation
}

# Optional: specify land cover source used for export (otherwise taken from voxcity.extras when available)
land_cover_source = 'OpenStreetMap'

# Export INX by passing the VoxCity object directly
export_inx(
    voxcity,
    output_directory=envimet_kwargs["output_directory"],
    file_basename=envimet_kwargs["file_basename"],
    land_cover_source=land_cover_source,
    author_name=envimet_kwargs["author_name"],
    model_description=envimet_kwargs["model_description"],
    domain_building_max_height_ratio=envimet_kwargs["domain_building_max_height_ratio"],
    useTelescoping_grid=envimet_kwargs["useTelescoping_grid"],
    verticalStretch=envimet_kwargs["verticalStretch"],
    min_grids_Z=envimet_kwargs["min_grids_Z"],
)

# Generate plant database (EDB) for vegetation
generate_edb_file(lad=envimet_kwargs["lad"])

Example Output Exported in INX and Inported in ENVI-met

PALM Static Driver Files:

from voxcity.exporter.palm import export_palm

# Pass the VoxCity object directly; writes <domain_name>_static to output_directory
export_palm(
    voxcity,
    output_directory="output/palm",
    domain_name="voxcity",
    lad=1.0,              # Leaf Area Density (m2/m3) inside tree crowns
    buildings_3d="auto",  # write the domain-wide LOD2 building mask only when some building needs it (LOD1 alone can't express it)
)

PALM is an open-source large-eddy simulation (LES) model widely used for atmospheric boundary-layer and urban-climate research. export_palm writes a single PIDS-conformant NetCDF <domain_name>_static file — terrain, buildings (2D + optional 3D), surface classification, and leaf area density — validated against PALM’s documented consistency rules before it’s written.

Namelist note: building footprints are deliberately left without a ground surface class (matching PALM’s own reference drivers), so a domain with buildings needs the urban surface model enabled in your _p3d (&urban_surface_parameters, alongside &land_surface_parameters and a radiation scheme). Running with only the land surface model makes PALM reject the driver with DRV0021 at those footprint cells. Dynamics-only runs (no surface-energy namelists at all) accept the driver as plain topography.

OBJ Files:

from voxcity.exporter.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
# Pass the VoxCity object directly (voxel size inferred)
export_obj(voxcity, output_directory, output_file_name)

The generated OBJ files can be opened and rendered in the following 3D visualization software:

• Twinmotion: Real-time visualization tool (Free for personal use)
• Blender: Professional-grade 3D creation suite (Free)
• Rhino: Professional 3D modeling software (Commercial, offers educational licenses)

Example Output Exported in OBJ and Rendered in Rhino

MagicaVoxel VOX Files:

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 voxcity.exporter.magicavoxel import export_magicavoxel_vox

output_path = "output"
base_filename = "voxcity"
# Pass the VoxCity object directly
export_magicavoxel_vox(voxcity, output_path, base_filename=base_filename)

Example Output Exported in VOX and Rendered in MagicaVoxel

from voxcity.exporter.geotiff import export_geotiffs
from voxcity.exporter.netcdf import save_voxel_netcdf
from voxcity.exporter.cityles import export_cityles

export_geotiffs(voxcity, "output/geotiff")     # land cover, building height, DEM, canopy height
save_voxel_netcdf(voxcity.voxels.classes, "output/voxcity.nc",
                  voxel_size_m=meshsize, rectangle_vertices=rectangle_vertices)
export_cityles(voxcity, output_directory="output/cityles")

from voxcity.generator import save_voxcity, load_voxcity

save_voxcity("output/voxcity.h5", voxcity)
voxcity = load_voxcity("output/voxcity.h5")

get_voxcity also saves output/voxcity.h5 automatically.

Building

Your own buildings: Local file (a GeoPackage given as building_path), a GeoDataFrame via building_gdf, CityGML via get_voxcity_CityGML, or Rhino OBJ via add_buildings_from_obj.

Tree Canopy Height

Land Cover

Terrain Elevation