voxcity.generator.api

Functions

auto_select_data_sources(rectangle_vertices)

Automatically choose data sources for buildings, land cover, canopy height, and DEM

get_voxcity(rectangle_vertices, meshsize[, ...])

Generate a VoxCity model with automatic or custom data source selection.

get_voxcity_CityGML(rectangle_vertices, ...[, ...])

Module Contents

voxcity.generator.api.auto_select_data_sources(rectangle_vertices)

Automatically choose data sources for buildings, land cover, canopy height, and DEM based on the target area’s location.

Rules (heuristic, partially inferred from latest availability): - Buildings (base): ‘OpenStreetMap’. - Buildings (complementary):

  • USA, Europe, Australia -> ‘Microsoft Building Footprints’

  • England -> ‘England 1m DSM - DTM’ (height from DSM-DTM)

  • Netherlands -> ‘Netherlands 0.5m DSM - DTM’ (height from DSM-DTM)

  • Africa, South Asia, SE Asia, Latin America & Caribbean -> ‘Open Building 2.5D Temporal’

  • Otherwise -> ‘None’

  • Land cover: USA -> ‘Urbanwatch’; Japan -> ‘OpenEarthMapJapan’; otherwise ‘OpenStreetMap’. (If OSM is insufficient, consider ‘ESA WorldCover’ manually.)

  • Canopy height: ‘High Resolution 1m Global Canopy Height Maps’.

  • DEM: High-resolution where available (USA, England, Australia, France, Netherlands), else ‘FABDEM’.

Returns a dict with keys: building_source, building_complementary_source, land_cover_source, canopy_height_source, dem_source.

voxcity.generator.api.get_voxcity(rectangle_vertices, meshsize, building_source=None, land_cover_source=None, canopy_height_source=None, dem_source=None, building_complementary_source=None, building_gdf=None, terrain_gdf=None, **kwargs)

Generate a VoxCity model with automatic or custom data source selection.

This function supports both auto mode and custom mode: - Auto mode: When sources are not specified (None), they are automatically selected based on location - Custom mode: When sources are explicitly specified, they are used as-is - Hybrid mode: Specify some sources and auto-select others

Parameters:

  • rectangle_vertices – List of (lon, lat) tuples defining the area of interest

  • meshsize – Grid resolution in meters (required)

  • building_source – Building base source (default: auto-selected based on location)

  • land_cover_source – Land cover source (default: auto-selected based on location)

  • canopy_height_source – Canopy height source (default: auto-selected based on location)

  • dem_source – Digital elevation model source (default: auto-selected based on location)

  • building_complementary_source – Building complementary source (default: auto-selected based on location)

  • building_gdf – Optional pre-loaded building GeoDataFrame

  • terrain_gdf – Optional pre-loaded terrain GeoDataFrame

  • **kwargs – Additional options for building, land cover, canopy, DEM, visualization, and I/O. Performance options include: - parallel_download: bool, if True downloads run concurrently (default: False) I/O options include: - output_dir: Directory for intermediate/downloaded data (default: “output”) - save_path: Full file path to save the VoxCity object (overrides output_dir default) - save_voxcity_data / save_voxctiy_data: bool flag to enable saving (default: True)

Returns:

VoxCity object containing the generated 3D city model

voxcity.generator.api.get_voxcity_CityGML(rectangle_vertices, land_cover_source, canopy_height_source, meshsize, url_citygml=None, citygml_path=None, **kwargs)