voxcity.generator.update

Functions for updating VoxCity objects with new grid data.

Functions

update_voxcity(→ voxcity.models.VoxCity)

Update a VoxCity object with new grid data and regenerate the VoxelGrid.

regenerate_voxels(→ voxcity.models.VoxCity)

Regenerate only the VoxelGrid from existing component grids.

Module Contents

voxcity.generator.update.update_voxcity(city: voxcity.models.VoxCity, *, buildings: voxcity.models.BuildingGrid | None = None, building_heights: numpy.ndarray | None = None, building_min_heights: numpy.ndarray | None = None, building_ids: numpy.ndarray | None = None, land_cover: voxcity.models.LandCoverGrid | numpy.ndarray | None = None, dem: voxcity.models.DemGrid | numpy.ndarray | None = None, tree_canopy: voxcity.models.CanopyGrid | numpy.ndarray | None = None, canopy_top: numpy.ndarray | None = None, canopy_bottom: numpy.ndarray | None = None, building_gdf=None, tree_gdf=None, tree_gdf_mode: str = 'replace', land_cover_source: str | None = None, trunk_height_ratio: float | None = None, voxel_dtype=None, max_voxel_ram_mb: float | None = None, inplace: bool = False) → voxcity.models.VoxCity

Update a VoxCity object with new grid data and regenerate the VoxelGrid.

This function allows partial updates - only the grids you provide will be updated, while the rest will be taken from the existing VoxCity object. The VoxelGrid is always regenerated from the (updated) component grids.

Parameters:

  • city (VoxCity) – The existing VoxCity object to update.

  • buildings (BuildingGrid, optional) – Complete replacement for the building grid. If provided, takes precedence over individual building_heights/building_min_heights/building_ids.

  • building_heights (np.ndarray, optional) – 2D array of building heights. If buildings is not provided, this updates only the heights while keeping existing min_heights and ids.

  • building_min_heights (np.ndarray, optional) – 2D object-dtype array of lists containing [min_height, max_height] pairs for each building segment per cell.

  • building_ids (np.ndarray, optional) – 2D array of building IDs per cell.

  • land_cover (LandCoverGrid or np.ndarray, optional) – New land cover data. Can be a LandCoverGrid or a raw numpy array.

  • dem (DemGrid or np.ndarray, optional) – New DEM/elevation data. Can be a DemGrid or a raw numpy array.

  • tree_canopy (CanopyGrid or np.ndarray, optional) – New tree canopy data. Can be a CanopyGrid (with top/bottom) or a raw numpy array (interpreted as canopy top heights).

  • canopy_top (np.ndarray, optional) – 2D array of tree canopy top heights. Takes precedence over tree_canopy for top heights if both are provided.

  • canopy_bottom (np.ndarray, optional) – 2D array of tree canopy bottom heights (crown base).

  • building_gdf (GeoDataFrame, optional) – Updated building GeoDataFrame. If provided without building grids (building_heights, building_min_heights, building_ids), the function will automatically generate the building grids from the GeoDataFrame using create_building_height_grid_from_gdf_polygon. The GeoDataFrame is also stored in city.extras[‘building_gdf’].

  • tree_gdf (GeoDataFrame, optional) – Updated tree GeoDataFrame. If provided without tree canopy data (tree_canopy, canopy_top, canopy_bottom), the function will automatically generate the canopy grids from the GeoDataFrame using create_canopy_grids_from_tree_gdf. The GeoDataFrame must contain ‘top_height’, ‘bottom_height’, ‘crown_diameter’, and ‘geometry’ columns. The GeoDataFrame is stored in city.extras[‘tree_gdf’].

  • tree_gdf_mode (str, default "replace") –

    How to combine tree_gdf with existing canopy data. Options: - “replace”: Replace the existing canopy grids with new ones from tree_gdf. - “add”: Merge the tree_gdf grids with existing (or provided) canopy grids

    by taking the maximum height at each cell (preserves existing trees). When canopy_top/canopy_bottom are also provided, the tree_gdf grids are merged on top of those arrays instead of the existing city canopy.

  • land_cover_source (str, optional) – The land cover source name for proper voxelization. If not provided, attempts to use the source from city.extras or defaults to ‘OpenStreetMap’.

  • trunk_height_ratio (float, optional) – Ratio of trunk height to total tree height for canopy bottom calculation. Default is approximately 0.588 (11.76/19.98).

  • voxel_dtype (dtype, optional) – NumPy dtype for the voxel grid. Defaults to np.int8.

  • max_voxel_ram_mb (float, optional) – Maximum RAM in MB for voxel grid allocation. Raises MemoryError if exceeded.

  • inplace (bool, default False) – If True, modifies the input city object directly and returns it. If False, creates and returns a new VoxCity object.

Returns:

The updated VoxCity object with regenerated VoxelGrid.

Return type:

VoxCity

Examples

Update building heights and regenerate voxels:

>>> import numpy as np
>>> new_heights = city.buildings.heights.copy()
>>> new_heights[10:20, 10:20] = 50.0  # Increase height in a region
>>> updated = update_voxcity(city, building_heights=new_heights)

Update with a complete new BuildingGrid:

>>> from voxcity.models import BuildingGrid
>>> new_buildings = BuildingGrid(heights=..., min_heights=..., ids=..., meta=city.buildings.meta)
>>> updated = update_voxcity(city, buildings=new_buildings)

Update land cover and DEM together:

>>> updated = update_voxcity(city, land_cover=new_lc_array, dem=new_dem_array)

Update buildings from GeoDataFrame (automatic grid generation):

>>> updated = update_voxcity(city, building_gdf=updated_building_gdf)

Update trees from GeoDataFrame (replace existing canopy):

>>> updated = update_voxcity(city, tree_gdf=updated_tree_gdf)

Add trees from GeoDataFrame to existing canopy:

>>> updated = update_voxcity(city, tree_gdf=new_tree_gdf, tree_gdf_mode="add")
voxcity.generator.update.regenerate_voxels(city: voxcity.models.VoxCity, *, land_cover_source: str | None = None, trunk_height_ratio: float | None = None, voxel_dtype=None, max_voxel_ram_mb: float | None = None, inplace: bool = False) → voxcity.models.VoxCity

Regenerate only the VoxelGrid from existing component grids.

This is a convenience function for when you’ve modified the grids in-place and need to regenerate the voxels without passing all parameters.

Parameters:

  • city (VoxCity) – The VoxCity object whose voxels should be regenerated.

  • land_cover_source (str, optional) – Land cover source for voxelization. Defaults to source from extras.

  • trunk_height_ratio (float, optional) – Trunk height ratio for tree canopy calculation.

  • voxel_dtype (dtype, optional) – NumPy dtype for voxel grid.

  • max_voxel_ram_mb (float, optional) – Maximum RAM in MB for voxel allocation.

  • inplace (bool, default False) – If True, modifies city directly; otherwise returns a new object.

Returns:

The VoxCity object with regenerated VoxelGrid.

Return type:

VoxCity

Examples

>>> # Modify building heights in place
>>> city.buildings.heights[50:60, 50:60] = 100.0
>>> # Regenerate voxels to reflect the change
>>> city = regenerate_voxels(city, inplace=True)