voxcity 0.5.14__py3-none-any.whl → 0.5.15__py3-none-any.whl

voxcity/generator.py

@@ -14,9 +14,13 @@ The main functions are:
 - get_voxcity: Main function to generate a complete voxel city model
 """
 
+# Standard library imports
 import numpy as np
 import os
+
 # Local application/library specific imports
+
+# Data downloaders - modules for fetching geospatial data from various sources
 from .downloader.mbfp import get_mbfp_gdf
 from .downloader.osm import load_gdf_from_openstreetmap, load_land_cover_gdf_from_osm
 from .downloader.oemj import save_oemj_as_geotiff
@@ -24,6 +28,8 @@ from .downloader.omt import load_gdf_from_openmaptiles
 from .downloader.eubucco import load_gdf_from_eubucco
 from .downloader.overture import load_gdf_from_overture
 from .downloader.citygml import load_buid_dem_veg_from_citygml
+
+# Google Earth Engine related imports - for satellite and elevation data
 from .downloader.gee import (
     initialize_earth_engine,
     get_roi,
@@ -37,6 +43,8 @@ from .downloader.gee import (
     save_geotiff_open_buildings_temporal,
     save_geotiff_dsm_minus_dtm
 )
+
+# Grid processing functions - for converting geodata to raster grids
 from .geoprocessor.grid import (
     group_and_label_cells, 
     process_grid,
@@ -49,8 +57,12 @@ from .geoprocessor.grid import (
     create_vegetation_height_grid_from_gdf_polygon,
     create_dem_grid_from_gdf_polygon
 )
+
+# Utility functions
 from .utils.lc import convert_land_cover, convert_land_cover_array
 from .geoprocessor.polygon import get_gdf_from_gpkg, save_geojson
+
+# Visualization functions - for creating plots and 3D visualizations
 from .utils.visualization import (
     get_land_cover_classes,
     visualize_land_cover_grid,
@@ -83,55 +95,70 @@ def get_land_cover_grid(rectangle_vertices, meshsize, source, output_dir, **kwar
     print("Creating Land Use Land Cover grid\n ")
     print(f"Data source: {source}")
     
-    # Initialize Earth Engine for accessing satellite data
+    # Initialize Earth Engine for satellite-based data sources
+    # Skip initialization for local/vector data sources
     if source not in ["OpenStreetMap", "OpenEarthMapJapan"]:
         initialize_earth_engine()
 
-    # Create output directory if it doesn't exist
+    # Ensure output directory exists for saving intermediate files
     os.makedirs(output_dir, exist_ok=True)
     geotiff_path = os.path.join(output_dir, "land_cover.tif")
 
-    # Get land cover data based on selected source
+    # Handle different data sources - each requires specific processing
+    # Satellite/raster-based sources are saved as GeoTIFF files
     if source == 'Urbanwatch':
+        # Urban-focused land cover from satellite imagery
         roi = get_roi(rectangle_vertices)
         collection_name = "projects/sat-io/open-datasets/HRLC/urban-watch-cities"
         image = get_ee_image_collection(collection_name, roi)
         save_geotiff(image, geotiff_path)
     elif source == 'ESA WorldCover':
+        # Global land cover from European Space Agency
         roi = get_roi(rectangle_vertices)
         save_geotiff_esa_land_cover(roi, geotiff_path)
     elif source == 'ESRI 10m Annual Land Cover':
+        # High-resolution annual land cover from ESRI
         esri_landcover_year = kwargs.get("esri_landcover_year")
         roi = get_roi(rectangle_vertices)
         save_geotiff_esri_landcover(roi, geotiff_path, year=esri_landcover_year)
     elif source == 'Dynamic World V1':
+        # Near real-time land cover from Google's Dynamic World
         dynamic_world_date = kwargs.get("dynamic_world_date")
         roi = get_roi(rectangle_vertices)
         save_geotiff_dynamic_world_v1(roi, geotiff_path, dynamic_world_date)
     elif source == 'OpenEarthMapJapan':
+        # Japan-specific land cover dataset
         save_oemj_as_geotiff(rectangle_vertices, geotiff_path)   
     elif source == 'OpenStreetMap':
-        # For OSM, we get data directly as GeoJSON instead of GeoTIFF
+        # Vector-based land cover from OpenStreetMap
+        # This bypasses the GeoTIFF workflow and gets data directly as GeoJSON
         land_cover_gdf = load_land_cover_gdf_from_osm(rectangle_vertices)
     
-    # Get mapping of land cover classes for the selected source
+    # Get the classification scheme for the selected data source
+    # Each source has its own land cover categories and color coding
     land_cover_classes = get_land_cover_classes(source)
 
-    # Create grid from either GeoJSON (OSM) or GeoTIFF (other sources)
+    # Convert geospatial data to regular grid format
+    # Different processing for vector vs raster data sources
     if source == 'OpenStreetMap':
+        # Process vector data directly from GeoDataFrame
         land_cover_grid_str = create_land_cover_grid_from_gdf_polygon(land_cover_gdf, meshsize, source, rectangle_vertices)
     else:
+        # Process raster data from GeoTIFF file
         land_cover_grid_str = create_land_cover_grid_from_geotiff_polygon(geotiff_path, meshsize, land_cover_classes, rectangle_vertices)
 
-    # Create color map for visualization, scaling RGB values to 0-1 range
+    # Prepare color mapping for visualization
+    # Convert RGB values from 0-255 range to 0-1 range for matplotlib
     color_map = {cls: [r/255, g/255, b/255] for (r,g,b), cls in land_cover_classes.items()}
 
-    # Visualize grid if requested
+    # Generate visualization if requested
     grid_vis = kwargs.get("gridvis", True)    
     if grid_vis:
+        # Flip grid vertically for correct display orientation
         visualize_land_cover_grid(np.flipud(land_cover_grid_str), meshsize, color_map, land_cover_classes)
     
-    # Convert string labels to integer codes
+    # Convert string-based land cover labels to integer codes for processing
+    # This enables efficient numerical operations on the grid
     land_cover_grid_int = convert_land_cover_array(land_cover_grid_str, land_cover_classes)
 
     return land_cover_grid_int
@@ -159,7 +186,7 @@ def get_building_height_grid(rectangle_vertices, meshsize, source, output_dir, *
             - list: Filtered building features
     """
 
-    # Initialize Earth Engine for accessing satellite data
+    # Initialize Earth Engine for satellite-based building data sources
     if source not in ["OpenStreetMap", "Overture", "Local file"]:
         initialize_earth_engine()
 
@@ -168,52 +195,60 @@ def get_building_height_grid(rectangle_vertices, meshsize, source, output_dir, *
 
     os.makedirs(output_dir, exist_ok=True)
     
-    # Get building data from primary source
+    # Fetch building data from primary source
+    # Each source has different data formats and processing requirements
     if source == 'Microsoft Building Footprints':
+        # Machine learning-derived building footprints from satellite imagery
         gdf = get_mbfp_gdf(output_dir, rectangle_vertices)
     elif source == 'OpenStreetMap':
+        # Crowd-sourced building data with varying completeness
         gdf = load_gdf_from_openstreetmap(rectangle_vertices)
     elif source == "Open Building 2.5D Temporal":
-        # Special case: directly creates grids without intermediate GeoJSON
+        # Special case: this source provides both footprints and heights
+        # Skip GeoDataFrame processing and create grids directly
         building_height_grid, building_min_height_grid, building_id_grid, filtered_buildings = create_building_height_grid_from_open_building_temporal_polygon(meshsize, rectangle_vertices, output_dir)
     elif source == 'EUBUCCO v0.1':
+        # European building database with height information
         gdf = load_gdf_from_eubucco(rectangle_vertices, output_dir)
     elif source == "OpenMapTiles":
+        # Vector tiles service for building data
         gdf = load_gdf_from_openmaptiles(rectangle_vertices, kwargs["maptiler_API_key"])
     elif source == "Overture":
+        # Open building dataset from Overture Maps Foundation
         gdf = load_gdf_from_overture(rectangle_vertices)
     elif source == "Local file":
-        # Handle local GPKG files
+        # Handle user-provided local building data files
         _, extension = os.path.splitext(kwargs["building_path"])
         if extension == ".gpkg":
             gdf = get_gdf_from_gpkg(kwargs["building_path"], rectangle_vertices)
     
-    # Check for complementary building data source
+    # Handle complementary data sources to fill gaps or provide additional information
+    # This allows combining multiple sources for better coverage or accuracy
     building_complementary_source = kwargs.get("building_complementary_source") 
     building_complement_height = kwargs.get("building_complement_height")
 
     if (building_complementary_source is None) or (building_complementary_source=='None'):
-        # Use only primary source
+        # Use only the primary data source
         if source != "Open Building 2.5D Temporal":
             building_height_grid, building_min_height_grid, building_id_grid, filtered_buildings = create_building_height_grid_from_gdf_polygon(gdf, meshsize, rectangle_vertices, complement_height=building_complement_height)
     else:
-        # Handle complementary source
+        # Combine primary source with complementary data
         if building_complementary_source == "Open Building 2.5D Temporal":
-            # Special case: use temporal height data as complement
+            # Use temporal height data to complement footprint data
             roi = get_roi(rectangle_vertices)
             os.makedirs(output_dir, exist_ok=True)
             geotiff_path_comp = os.path.join(output_dir, "building_height.tif")
             save_geotiff_open_buildings_temporal(roi, geotiff_path_comp)
             building_height_grid, building_min_height_grid, building_id_grid, filtered_buildings = create_building_height_grid_from_gdf_polygon(gdf, meshsize, rectangle_vertices, geotiff_path_comp=geotiff_path_comp, complement_height=building_complement_height)   
         elif building_complementary_source in ["England 1m DSM - DTM", "Netherlands 0.5m DSM - DTM"]:
-            # Special case: use temporal height data as complement
+            # Use digital surface model minus digital terrain model for height estimation
             roi = get_roi(rectangle_vertices)
             os.makedirs(output_dir, exist_ok=True)
             geotiff_path_comp = os.path.join(output_dir, "building_height.tif")
             save_geotiff_dsm_minus_dtm(roi, geotiff_path_comp, meshsize, building_complementary_source)
             building_height_grid, building_min_height_grid, building_id_grid, filtered_buildings = create_building_height_grid_from_gdf_polygon(gdf, meshsize, rectangle_vertices, geotiff_path_comp=geotiff_path_comp, complement_height=building_complement_height)
         else:
-            # Get complementary data from other sources
+            # Fetch complementary data from another vector source
             if building_complementary_source == 'Microsoft Building Footprints':
                 gdf_comp = get_mbfp_gdf(output_dir, rectangle_vertices)
             elif building_complementary_source == 'OpenStreetMap':
@@ -229,15 +264,18 @@ def get_building_height_grid(rectangle_vertices, meshsize, source, output_dir, *
                 if extension == ".gpkg":
                     gdf_comp = get_gdf_from_gpkg(kwargs["building_complementary_path"], rectangle_vertices)
             
-            # Option to complement footprints only or both footprints and heights
+            # Configure how to combine the complementary data
+            # Can complement footprints only or both footprints and heights
             complement_building_footprints = kwargs.get("complement_building_footprints")
             building_height_grid, building_min_height_grid, building_id_grid, filtered_buildings = create_building_height_grid_from_gdf_polygon(gdf, meshsize, rectangle_vertices, gdf_comp=gdf_comp, complement_building_footprints=complement_building_footprints, complement_height=building_complement_height)
 
-    # Visualize grid if requested
+    # Generate visualization if requested
     grid_vis = kwargs.get("gridvis", True)    
     if grid_vis:
+        # Replace zeros with NaN for better visualization (don't show empty areas)
         building_height_grid_nan = building_height_grid.copy()
         building_height_grid_nan[building_height_grid_nan == 0] = np.nan
+        # Flip grid vertically for correct display orientation
         visualize_numerical_grid(np.flipud(building_height_grid_nan), meshsize, "building height (m)", cmap='viridis', label='Value')
 
     return building_height_grid, building_min_height_grid, building_id_grid, filtered_buildings
@@ -260,32 +298,38 @@ def get_canopy_height_grid(rectangle_vertices, meshsize, source, output_dir, **k
     print("Creating Canopy Height grid\n ")
     print(f"Data source: High Resolution Canopy Height Maps by WRI and Meta")
     
-    # Initialize Earth Engine for accessing satellite data
+    # Initialize Earth Engine for satellite-based canopy height data
     initialize_earth_engine()
 
     os.makedirs(output_dir, exist_ok=True)
     geotiff_path = os.path.join(output_dir, "canopy_height.tif")
     
-    # Get region of interest and canopy height data
+    # Get region of interest and fetch canopy height data
     roi = get_roi(rectangle_vertices)
     if source == 'High Resolution 1m Global Canopy Height Maps':
+        # High-resolution (1m) global canopy height maps from Meta and WRI
+        # Based on satellite imagery and machine learning models
         collection_name = "projects/meta-forest-monitoring-okw37/assets/CanopyHeight"  
         image = get_ee_image_collection(collection_name, roi)      
     elif source == 'ETH Global Sentinel-2 10m Canopy Height (2020)':
+        # Medium-resolution (10m) canopy height from ETH Zurich
+        # Derived from Sentinel-2 satellite data
         collection_name = "users/nlang/ETH_GlobalCanopyHeight_2020_10m_v1"
         image = get_ee_image(collection_name, roi)
     
-    # Save canopy height data as GeoTIFF
+    # Save canopy height data as GeoTIFF with specified resolution
     save_geotiff(image, geotiff_path, resolution=meshsize)  
 
-    # Create height grid from GeoTIFF
+    # Convert GeoTIFF to regular grid format
     canopy_height_grid = create_height_grid_from_geotiff_polygon(geotiff_path, meshsize, rectangle_vertices)
 
-    # Visualize grid if requested
+    # Generate visualization if requested
     grid_vis = kwargs.get("gridvis", True)    
     if grid_vis:
+        # Replace zeros with NaN for better visualization (show only areas with trees)
         canopy_height_grid_nan = canopy_height_grid.copy()
         canopy_height_grid_nan[canopy_height_grid_nan == 0] = np.nan
+        # Use green color scheme appropriate for vegetation
         visualize_numerical_grid(np.flipud(canopy_height_grid_nan), meshsize, "Tree canopy height", cmap='Greens', label='Tree canopy height (m)')
 
     return canopy_height_grid
@@ -310,38 +354,45 @@ def get_dem_grid(rectangle_vertices, meshsize, source, output_dir, **kwargs):
     print(f"Data source: {source}")
 
     if source == "Local file":
+        # Use user-provided local DEM file
         geotiff_path = kwargs["dem_path"]
     else:
-        # Initialize Earth Engine for accessing elevation data
+        # Fetch DEM data from various satellite/government sources
         initialize_earth_engine()
 
         geotiff_path = os.path.join(output_dir, "dem.tif")
 
-        # Add buffer around ROI to ensure smooth interpolation at edges
+        # Add buffer around region of interest to ensure smooth interpolation at edges
+        # This prevents edge artifacts in the final grid
         buffer_distance = 100
         roi = get_roi(rectangle_vertices)
         roi_buffered = roi.buffer(buffer_distance)
         
-        # Get DEM data
+        # Fetch elevation data from selected source
         image = get_dem_image(roi_buffered, source)
         
-        # Save DEM data with appropriate resolution based on source
+        # Save DEM data with appropriate resolution based on source capabilities
         if source in ["England 1m DTM", 'DEM France 1m', 'DEM France 5m', 'AUSTRALIA 5M DEM', 'Netherlands 0.5m DTM']:
+            # High-resolution elevation models - use specified mesh size
             save_geotiff(image, geotiff_path, scale=meshsize, region=roi_buffered, crs='EPSG:4326')
         elif source == 'USGS 3DEP 1m':
+            # US Geological Survey 3D Elevation Program
+            # Ensure minimum scale of 1.25m due to data limitations
             scale = max(meshsize, 1.25)
             save_geotiff(image, geotiff_path, scale=scale, region=roi_buffered, crs='EPSG:4326')
         else:
-            # Default to 30m resolution for other sources
+            # Default to 30m resolution for global/lower resolution sources
             save_geotiff(image, geotiff_path, scale=30, region=roi_buffered)
 
-    # Create DEM grid with optional interpolation method
+    # Convert GeoTIFF to regular grid with optional interpolation
+    # Interpolation helps fill gaps and smooth transitions
     dem_interpolation = kwargs.get("dem_interpolation")
     dem_grid = create_dem_grid_from_geotiff_polygon(geotiff_path, meshsize, rectangle_vertices, dem_interpolation=dem_interpolation)
 
-    # Visualize grid if requested
+    # Generate visualization if requested
     grid_vis = kwargs.get("gridvis", True)    
     if grid_vis:
+        # Use terrain color scheme appropriate for elevation data
         visualize_numerical_grid(np.flipud(dem_grid), meshsize, title='Digital Elevation Model', cmap='terrain', label='Elevation (m)')
 
     return dem_grid
@@ -367,13 +418,16 @@ def create_3d_voxel(building_height_grid_ori, building_min_height_grid_ori, buil
 
     print("Generating 3D voxel data")
     
-    # Convert land cover values if not from OpenStreetMap
+    # Convert land cover values to standardized format if needed
+    # OpenStreetMap data is already in the correct format
     if (land_cover_source == 'OpenStreetMap'):
         land_cover_grid_converted = land_cover_grid_ori
     else:
         land_cover_grid_converted = convert_land_cover(land_cover_grid_ori, land_cover_source=land_cover_source)
 
-    # Prepare and flip all input grids vertically for consistent orientation
+    # Prepare all input grids for 3D processing
+    # Flip vertically to align with standard geographic orientation (north-up)
+    # Handle missing data appropriately for each grid type
     building_height_grid = np.flipud(np.nan_to_num(building_height_grid_ori, nan=10.0)) # Replace NaN values with 10m height
     building_min_height_grid = np.flipud(replace_nan_in_nested(building_min_height_grid_ori)) # Replace NaN in nested arrays
     building_id_grid = np.flipud(building_id_grid_ori)
@@ -382,61 +436,68 @@ def create_3d_voxel(building_height_grid_ori, building_min_height_grid_ori, buil
     dem_grid = process_grid(building_id_grid, dem_grid) # Process DEM based on building footprints
     tree_grid = np.flipud(tree_grid_ori.copy())
 
-    # Validate input dimensions
+    # Validate that all input grids have consistent dimensions
     assert building_height_grid.shape == land_cover_grid.shape == dem_grid.shape == tree_grid.shape, "Input grids must have the same shape"
 
     rows, cols = building_height_grid.shape
 
-    # Calculate required height for 3D grid - add 1 to ensure enough space
+    # Calculate the required height for the 3D voxel grid
+    # Add 1 voxel layer to ensure sufficient vertical space
     max_height = int(np.ceil(np.max(building_height_grid + dem_grid + tree_grid) / voxel_size))+1
 
-    # Initialize empty 3D grid
+    # Initialize the 3D voxel grid with zeros
+    # Dimensions: (rows, columns, height_layers)
     voxel_grid = np.zeros((rows, cols, max_height), dtype=np.int32)
 
-    # Get trunk height ratio for trees, default based on typical tree proportions
+    # Configure tree trunk-to-crown ratio
+    # This determines how much of the tree is trunk vs canopy
     trunk_height_ratio = kwargs.get("trunk_height_ratio")
     if trunk_height_ratio is None:
         trunk_height_ratio = 11.76 / 19.98  # Default ratio based on typical tree proportions
 
-    # Fill the 3D grid cell by cell
+    # Process each grid cell to build the 3D voxel representation
     for i in range(rows):
         for j in range(cols):
-            # Calculate ground level in voxel units (+1 to ensure space for surface features)
+            # Calculate ground level in voxel units
+            # Add 1 to ensure space for surface features
             ground_level = int(dem_grid[i, j] / voxel_size + 0.5) + 1 
 
+            # Extract current cell values
             tree_height = tree_grid[i, j]
             land_cover = land_cover_grid[i, j]
 
-            # Fill underground voxels with -1
+            # Fill underground voxels with -1 (represents subsurface)
             voxel_grid[i, j, :ground_level] = -1
 
-            # Set surface land cover value
+            # Set the ground surface to the land cover type
             voxel_grid[i, j, ground_level-1] = land_cover
 
-            # Process trees - split into trunk and crown sections
+            # Process tree canopy if trees are present
             if tree_height > 0:
-                # Calculate crown base and top heights
+                # Calculate tree structure: trunk base to crown base to crown top
                 crown_base_height = (tree_height * trunk_height_ratio)
                 crown_base_height_level = int(crown_base_height / voxel_size + 0.5)
                 crown_top_height = tree_height
                 crown_top_height_level = int(crown_top_height / voxel_size + 0.5)
                 
                 # Ensure minimum crown height of 1 voxel
+                # Prevent crown base and top from being at the same level
                 if (crown_top_height_level == crown_base_height_level) and (crown_base_height_level>0):
                     crown_base_height_level -= 1
                     
-                # Calculate tree start and end positions relative to ground level
+                # Calculate absolute positions relative to ground level
                 tree_start = ground_level + crown_base_height_level
                 tree_end = ground_level + crown_top_height_level
                 
-                # Fill tree crown voxels with -2
+                # Fill tree crown voxels with -2 (represents vegetation canopy)
                 voxel_grid[i, j, tree_start:tree_end] = -2
 
-            # Process buildings - handle multiple height segments
+            # Process buildings - handle multiple height segments per building
+            # Some buildings may have multiple levels or complex height profiles
             for k in building_min_height_grid[i, j]:
                 building_min_height = int(k[0] / voxel_size + 0.5)  # Lower height of building segment
                 building_height = int(k[1] / voxel_size + 0.5)      # Upper height of building segment
-                # Fill building voxels with -3
+                # Fill building voxels with -3 (represents built structures)
                 voxel_grid[i, j, ground_level+building_min_height:ground_level+building_height] = -3
 
     return voxel_grid
@@ -558,73 +619,89 @@ def get_voxcity(rectangle_vertices, building_source, land_cover_source, canopy_h
             - dem_grid: 2D grid of ground elevation
             - building_geojson: GeoJSON of building footprints and metadata
     """
-    # Create output directory if it doesn't exist
+    # Set up output directory for intermediate and final files
     output_dir = kwargs.get("output_dir", "output")
     os.makedirs(output_dir, exist_ok=True)
         
-    # Remove 'output_dir' from kwargs to prevent duplication
+    # Remove 'output_dir' from kwargs to prevent duplication in function calls
     kwargs.pop('output_dir', None)
 
-    # Generate all required 2D grids
+    # STEP 1: Generate all required 2D grids from various data sources
+    # These grids form the foundation for the 3D voxel model
+    
+    # Land cover classification grid (e.g., urban, forest, water, agriculture)
     land_cover_grid = get_land_cover_grid(rectangle_vertices, meshsize, land_cover_source, output_dir, **kwargs)
+    
+    # Building footprints and height information
     building_height_grid, building_min_height_grid, building_id_grid, building_gdf = get_building_height_grid(rectangle_vertices, meshsize, building_source, output_dir, **kwargs)
     
-    # Save building data to GeoJSON
+    # Save building data to file for later analysis or visualization
     if not building_gdf.empty:
         save_path = f"{output_dir}/building.gpkg"
         building_gdf.to_file(save_path, driver='GPKG')
     
-    # Get canopy height data
+    # STEP 2: Handle canopy height data
+    # Either use static values or fetch from satellite sources
     if canopy_height_source == "Static":
-        # Create canopy height grid with same shape as land cover grid
+        # Create uniform canopy height for all tree-covered areas
         canopy_height_grid = np.zeros_like(land_cover_grid, dtype=float)
         
-        # Set default static height for trees (20 meters is a typical average tree height)
+        # Apply static height to areas classified as trees
+        # Default height represents typical urban tree height
         static_tree_height = kwargs.get("static_tree_height", 10.0)
         tree_mask = (land_cover_grid == 4)
         
         # Set static height for tree cells
         canopy_height_grid[tree_mask] = static_tree_height
     else:
+        # Fetch canopy height from satellite/remote sensing sources
         canopy_height_grid = get_canopy_height_grid(rectangle_vertices, meshsize, canopy_height_source, output_dir, **kwargs)
     
-    # Handle DEM - either flat or from source
+    # STEP 3: Handle digital elevation model (terrain)
     if dem_source == "Flat":
+        # Create flat terrain for simplified modeling
         dem_grid = np.zeros_like(land_cover_grid)
     else:
+        # Fetch terrain elevation from various sources
         dem_grid = get_dem_grid(rectangle_vertices, meshsize, dem_source, output_dir, **kwargs)
 
-    # Apply minimum canopy height threshold if specified
+    # STEP 4: Apply optional data filtering and cleaning
+    
+    # Filter out low vegetation that may be noise in the data
     min_canopy_height = kwargs.get("min_canopy_height")
     if min_canopy_height is not None:
         canopy_height_grid[canopy_height_grid < kwargs["min_canopy_height"]] = 0        
 
-    # Remove objects near perimeter if specified
+    # Remove objects near the boundary to avoid edge effects
+    # This is useful when the area of interest is part of a larger urban area
     remove_perimeter_object = kwargs.get("remove_perimeter_object")
     if (remove_perimeter_object is not None) and (remove_perimeter_object > 0):
         # Calculate perimeter width based on grid dimensions
         w_peri = int(remove_perimeter_object * building_height_grid.shape[0] + 0.5)
         h_peri = int(remove_perimeter_object * building_height_grid.shape[1] + 0.5)
         
-        # Clear canopy heights in perimeter
+        # Clear canopy heights in perimeter areas
         canopy_height_grid[:w_peri, :] = canopy_height_grid[-w_peri:, :] = canopy_height_grid[:, :h_peri] = canopy_height_grid[:, -h_peri:] = 0
 
-        # Find building IDs in perimeter regions
+        # Identify buildings that intersect with perimeter areas
         ids1 = np.unique(building_id_grid[:w_peri, :][building_id_grid[:w_peri, :] > 0])
         ids2 = np.unique(building_id_grid[-w_peri:, :][building_id_grid[-w_peri:, :] > 0])
         ids3 = np.unique(building_id_grid[:, :h_peri][building_id_grid[:, :h_peri] > 0])
         ids4 = np.unique(building_id_grid[:, -h_peri:][building_id_grid[:, -h_peri:] > 0])
         remove_ids = np.concatenate((ids1, ids2, ids3, ids4))
         
-        # Remove buildings in perimeter
+        # Remove identified buildings from all grids
         for remove_id in remove_ids:
             positions = np.where(building_id_grid == remove_id)
             building_height_grid[positions] = 0
             building_min_height_grid[positions] = [[] for _ in range(len(building_min_height_grid[positions]))]
 
-    # Visualize 2D grids on map if requested
+    # STEP 5: Generate optional 2D visualizations on interactive maps
     mapvis = kwargs.get("mapvis")
     if mapvis:
+        # Create map-based visualizations of all data layers
+        # These help users understand the input data before 3D modeling
+        
         # Visualize land cover using the new function
         visualize_landcover_grid_on_basemap(
             land_cover_grid, 
@@ -676,20 +753,22 @@ def get_voxcity(rectangle_vertices, building_source, land_cover_source, canopy_h
             show_edge=False
         )
 
-    # Generate 3D voxel grid
+    # STEP 6: Generate the final 3D voxel model
+    # This combines all 2D grids into a comprehensive 3D representation
     voxcity_grid = create_3d_voxel(building_height_grid, building_min_height_grid, building_id_grid, land_cover_grid, dem_grid, canopy_height_grid, meshsize, land_cover_source)
 
-    # Visualize 3D model if requested
+    # STEP 7: Generate optional 3D visualization
     voxelvis = kwargs.get("voxelvis")
     if voxelvis:
-        # Create taller visualization grid with fixed height
+        # Create a taller grid for better visualization
+        # Fixed height ensures consistent camera positioning
         new_height = int(550/meshsize+0.5)     
         voxcity_grid_vis = np.zeros((voxcity_grid.shape[0], voxcity_grid.shape[1], new_height))
         voxcity_grid_vis[:, :, :voxcity_grid.shape[2]] = voxcity_grid
         voxcity_grid_vis[-1, -1, -1] = -99  # Add marker to fix camera location and angle of view
         visualize_3d_voxel(voxcity_grid_vis, voxel_size=meshsize, save_path=kwargs["voxelvis_img_save_path"])
 
-    # Save all data if a save path is provided
+    # STEP 8: Save all generated data for future use
     save_voxcity = kwargs.get("save_voxctiy_data", True)
     if save_voxcity:
         save_path = kwargs.get("save_data_path", f"{output_dir}/voxcity_data.pkl")
@@ -845,18 +924,19 @@ def replace_nan_in_nested(arr, replace_value=10.0):
     Returns:
         Numpy array with NaN values replaced
     """
-    # Convert array to list for easier manipulation
+    # Convert array to list for easier manipulation of nested structures
     arr = arr.tolist()
     
-    # Iterate through all dimensions
+    # Iterate through all dimensions of the nested array
     for i in range(len(arr)):
         for j in range(len(arr[i])):
-            # Check if the element is a list
+            # Check if the element is a list (building height segments)
             if arr[i][j]:  # if not empty list
                 for k in range(len(arr[i][j])):
-                    # For each innermost list
+                    # For each innermost list (individual height segment)
                     if isinstance(arr[i][j][k], list):
                         for l in range(len(arr[i][j][k])):
+                            # Replace NaN values with the specified replacement value
                             if isinstance(arr[i][j][k][l], float) and np.isnan(arr[i][j][k][l]):
                                 arr[i][j][k][l] = replace_value
     
@@ -883,10 +963,11 @@ def save_voxcity_data(output_path, voxcity_grid, building_height_grid, building_
     import pickle
     import os
     
-    # Create directory if it doesn't exist
+    # Ensure the output directory exists
     os.makedirs(os.path.dirname(output_path), exist_ok=True)
     
-    # Create a dictionary with all the data
+    # Create a comprehensive dictionary containing all voxcity data
+    # This preserves all components needed to reconstruct or analyze the model
     data_dict = {
         'voxcity_grid': voxcity_grid,
         'building_height_grid': building_height_grid,
@@ -900,7 +981,8 @@ def save_voxcity_data(output_path, voxcity_grid, building_height_grid, building_
         'rectangle_vertices': rectangle_vertices
     }
     
-    # Save the data to a file using pickle
+    # Serialize and save the data using pickle for efficient storage
+    # Pickle preserves exact data types and structures
     with open(output_path, 'wb') as f:
         pickle.dump(data_dict, f)
     
@@ -927,13 +1009,14 @@ def load_voxcity_data(input_path):
     """
     import pickle
     
-    # Load the data from the file
+    # Deserialize the data from the saved file
     with open(input_path, 'rb') as f:
         data_dict = pickle.load(f)
     
     print(f"Voxcity data loaded from {input_path}")
     
-    # Return all components as a tuple
+    # Return all components as a tuple in the same order as the main function
+    # This ensures compatibility with existing code that expects this structure
     return (
         data_dict['voxcity_grid'],
         data_dict['building_height_grid'],