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

voxcity/utils/lc.py

@@ -1,12 +1,40 @@
+"""
+Land Cover Classification Utilities for VoxelCity
+
+This module provides utilities for handling land cover data from various sources,
+including color-based classification, data conversion between different land cover
+classification systems, and spatial analysis of land cover polygons.
+
+Supported land cover data sources:
+- Urbanwatch
+- OpenEarthMapJapan
+- ESRI 10m Annual Land Cover
+- ESA WorldCover
+- Dynamic World V1
+- OpenStreetMap
+- Standard classification
+"""
+
 import numpy as np
 from shapely.geometry import Polygon
 from rtree import index
 from collections import Counter
 
 def rgb_distance(color1, color2):
+    """
+    Calculate the Euclidean distance between two RGB colors.
+    
+    Args:
+        color1 (tuple): RGB values as (R, G, B) tuple
+        color2 (tuple): RGB values as (R, G, B) tuple
+        
+    Returns:
+        float: Euclidean distance between the two colors
+    """
     return np.sqrt(np.sum((np.array(color1) - np.array(color2))**2))  
 
 
+# Legacy land cover classes mapping - kept for reference
 # land_cover_classes = {
 #     (128, 0, 0): 'Bareland',              0         
 #     (0, 255, 36): 'Rangeland',            1
@@ -24,7 +52,27 @@ def rgb_distance(color1, color2):
 # }
 
 def get_land_cover_classes(source):
+    """
+    Get land cover classification mapping for a specific data source.
+    
+    Each data source has its own color-to-class mapping system. This function
+    returns the appropriate RGB color to land cover class dictionary based on
+    the specified source.
+    
+    Args:
+        source (str): Name of the land cover data source. Supported sources:
+                     "Urbanwatch", "OpenEarthMapJapan", "ESRI 10m Annual Land Cover",
+                     "ESA WorldCover", "Dynamic World V1", "Standard", "OpenStreetMap"
+                     
+    Returns:
+        dict: Dictionary mapping RGB tuples to land cover class names
+        
+    Example:
+        >>> classes = get_land_cover_classes("Urbanwatch")
+        >>> print(classes[(255, 0, 0)])  # Returns 'Building'
+    """
     if source == "Urbanwatch":
+        # Urbanwatch color scheme - focused on urban features
         land_cover_classes = {
             (255, 0, 0): 'Building',
             (133, 133, 133): 'Road',
@@ -38,6 +86,7 @@ def get_land_cover_classes(source):
             (0, 0, 0): 'Sea'
         }    
     elif (source == "OpenEarthMapJapan"):
+        # OpenEarthMap Japan specific classification
         land_cover_classes = {
             (128, 0, 0): 'Bareland',
             (0, 255, 36): 'Rangeland',
@@ -49,6 +98,7 @@ def get_land_cover_classes(source):
             (222, 31, 7): 'Building'
         }
     elif source == "ESRI 10m Annual Land Cover":
+        # ESRI's global 10-meter resolution land cover classification
         land_cover_classes = {
             (255, 255, 255): 'No Data',
             (26, 91, 171): 'Water',
@@ -63,6 +113,7 @@ def get_land_cover_classes(source):
             (200, 200, 200): 'Clouds'
         }
     elif source == "ESA WorldCover":
+        # European Space Agency WorldCover 10m classification
         land_cover_classes = {
             (0, 112, 0): 'Trees',
             (255, 224, 80): 'Shrubland',
@@ -77,6 +128,7 @@ def get_land_cover_classes(source):
             (255, 255, 0): 'Moss and lichen'
         }
     elif source == "Dynamic World V1":
+        # Google's Dynamic World near real-time land cover
         # Convert hex colors to RGB tuples
         land_cover_classes = {
             (65, 155, 223): 'Water',            # #419bdf
@@ -90,6 +142,7 @@ def get_land_cover_classes(source):
             (179, 159, 225): 'Snow and Ice'     # #b39fe1
         }
     elif (source == 'Standard') or (source == "OpenStreetMap"):
+        # Standard/OpenStreetMap classification - comprehensive land cover types
         land_cover_classes = {
             (128, 0, 0): 'Bareland',
             (0, 255, 36): 'Rangeland',
@@ -108,6 +161,7 @@ def get_land_cover_classes(source):
         }
     return land_cover_classes
 
+# Legacy land cover classes with numeric indices - kept for reference
 # land_cover_classes = {
 #     (128, 0, 0): 'Bareland',              0         
 #     (0, 255, 36): 'Rangeland',            1
@@ -128,6 +182,37 @@ def get_land_cover_classes(source):
 
 
 def convert_land_cover(input_array, land_cover_source='Urbanwatch'):   
+    """
+    Convert land cover classification from source-specific indices to standardized indices.
+    
+    This function maps land cover classes from various data sources to a standardized
+    classification system. Each source has different class definitions and indices,
+    so this conversion enables consistent processing across different data sources.
+    
+    Args:
+        input_array (numpy.ndarray): Input array with source-specific land cover indices
+        land_cover_source (str): Name of the source land cover classification system
+                                Default is 'Urbanwatch'
+                                
+    Returns:
+        numpy.ndarray: Array with standardized land cover indices
+        
+    Standardized Classification System:
+        0: Bareland
+        1: Rangeland  
+        2: Shrub
+        3: Agriculture land
+        4: Tree
+        5: Moss and lichen
+        6: Wet land
+        7: Mangrove
+        8: Water
+        9: Snow and ice
+        10: Developed space
+        11: Road
+        12: Building
+        13: No Data
+    """
 
     if land_cover_source == 'Urbanwatch':
         # Define the mapping from Urbanwatch to new standardized classes
@@ -144,6 +229,7 @@ def convert_land_cover(input_array, land_cover_source='Urbanwatch'):
             9: 8    # Sea -> Water
         }
     elif land_cover_source == 'ESA WorldCover':
+        # ESA WorldCover to standardized mapping
         convert_dict = {
             0: 4,   # Trees -> Tree
             1: 2,   # Shrubland -> Shrub
@@ -158,6 +244,7 @@ def convert_land_cover(input_array, land_cover_source='Urbanwatch'):
             10: 5   # Moss and lichen
         }
     elif land_cover_source == "ESRI 10m Annual Land Cover":
+        # ESRI 10m to standardized mapping
         convert_dict = {
             0: 13,  # No Data
             1: 8,   # Water
@@ -172,6 +259,7 @@ def convert_land_cover(input_array, land_cover_source='Urbanwatch'):
             10: 13  # Clouds -> No Data
         }
     elif land_cover_source == "Dynamic World V1":
+        # Dynamic World to standardized mapping
         convert_dict = {
             0: 8,   # Water
             1: 4,   # Trees -> Tree
@@ -184,6 +272,7 @@ def convert_land_cover(input_array, land_cover_source='Urbanwatch'):
             8: 9    # Snow and Ice
         }    
     elif land_cover_source == "OpenEarthMapJapan":
+        # OpenEarthMapJapan to standardized mapping
         convert_dict = {
             0: 0,   # Bareland
             1: 1,   # Rangeland
@@ -204,6 +293,26 @@ def convert_land_cover(input_array, land_cover_source='Urbanwatch'):
     return converted_array
 
 def get_class_priority(source):
+    """
+    Get priority rankings for land cover classes to resolve conflicts during classification.
+    
+    When multiple land cover classes are present in the same area, this priority system
+    determines which class should take precedence. Higher priority values indicate
+    classes that should override lower priority classes.
+    
+    Args:
+        source (str): Name of the land cover data source
+        
+    Returns:
+        dict: Dictionary mapping class names to priority values (higher = more priority)
+        
+    Priority Logic for OpenStreetMap:
+        - Built Environment: Highest priority (most definitive structures)
+        - Water Bodies: High priority (clearly defined features)  
+        - Vegetation: Medium priority (managed vs natural)
+        - Natural Non-Vegetation: Lower priority (often default classifications)
+        - Uncertain/No Data: Lowest priority
+    """
     if source == "OpenStreetMap":
         return {
             # Built Environment (highest priority as they're most definitively mapped)
@@ -230,6 +339,7 @@ def get_class_priority(source):
             # Uncertain
             'No Data': 14            # Lowest priority as it represents uncertainty
         }
+        # Legacy priority system - kept for reference
         # return { 
         #     'Bareland': 4, 
         #     'Rangeland': 6, 
@@ -242,6 +352,26 @@ def get_class_priority(source):
         # }
 
 def create_land_cover_polygons(land_cover_geojson):
+    """
+    Create polygon geometries and spatial index from land cover GeoJSON data.
+    
+    This function processes GeoJSON land cover data to create Shapely polygon
+    geometries and builds an R-tree spatial index for efficient spatial queries.
+    
+    Args:
+        land_cover_geojson (list): List of GeoJSON feature dictionaries containing
+                                  land cover polygons with geometry and properties
+                                  
+    Returns:
+        tuple: A tuple containing:
+            - land_cover_polygons (list): List of tuples (polygon, class_name)
+            - idx (rtree.index.Index): Spatial index for efficient polygon lookup
+            
+    Note:
+        Each GeoJSON feature should have:
+        - geometry.coordinates[0]: List of coordinate pairs defining the polygon
+        - properties.class: String indicating the land cover class
+    """
     land_cover_polygons = []
     idx = index.Index()
     count = 0
@@ -262,19 +392,72 @@ def create_land_cover_polygons(land_cover_geojson):
     return land_cover_polygons, idx
 
 def get_nearest_class(pixel, land_cover_classes):
+    """
+    Find the nearest land cover class for a given pixel color using RGB distance.
+    
+    This function determines the most appropriate land cover class for a pixel
+    by finding the class with the minimum RGB color distance to the pixel's color.
+    
+    Args:
+        pixel (tuple): RGB color values as (R, G, B) tuple
+        land_cover_classes (dict): Dictionary mapping RGB tuples to class names
+        
+    Returns:
+        str: Name of the nearest land cover class
+        
+    Example:
+        >>> classes = {(255, 0, 0): 'Building', (0, 255, 0): 'Tree'}
+        >>> nearest = get_nearest_class((250, 5, 5), classes)
+        >>> print(nearest)  # Returns 'Building'
+    """
     distances = {class_name: rgb_distance(pixel, color) 
                  for color, class_name in land_cover_classes.items()}
     return min(distances, key=distances.get)
 
 def get_dominant_class(cell_data, land_cover_classes):
+    """
+    Determine the dominant land cover class in a cell based on pixel majority.
+    
+    This function analyzes all pixels within a cell, classifies each pixel to its
+    nearest land cover class, and returns the most frequently occurring class.
+    
+    Args:
+        cell_data (numpy.ndarray): 3D array of RGB pixel data for the cell
+        land_cover_classes (dict): Dictionary mapping RGB tuples to class names
+        
+    Returns:
+        str: Name of the dominant land cover class in the cell
+        
+    Note:
+        If the cell contains no data, returns 'No Data'
+    """
     if cell_data.size == 0:
         return 'No Data'
+    # Classify each pixel in the cell to its nearest land cover class
     pixel_classes = [get_nearest_class(tuple(pixel), land_cover_classes) 
                      for pixel in cell_data.reshape(-1, 3)]
+    # Count occurrences of each class
     class_counts = Counter(pixel_classes)
+    # Return the most common class
     return class_counts.most_common(1)[0][0]
 
 def convert_land_cover_array(input_array, land_cover_classes):
+    """
+    Convert an array of land cover class names to integer indices.
+    
+    This function maps string-based land cover class names to integer indices
+    for numerical processing and storage efficiency.
+    
+    Args:
+        input_array (numpy.ndarray): Array containing land cover class names as strings
+        land_cover_classes (dict): Dictionary mapping RGB tuples to class names
+        
+    Returns:
+        numpy.ndarray: Array with integer indices corresponding to land cover classes
+        
+    Note:
+        Classes not found in the mapping are assigned index -1
+    """
     # Create a mapping of class names to integers
     class_to_int = {name: i for i, name in enumerate(land_cover_classes.values())}
 

voxcity/utils/material.py

@@ -1,8 +1,27 @@
+"""
+Material utilities for VoxelCity voxel grid processing.
+
+This module provides functions for setting building materials and window patterns
+in 3D voxel grids based on building IDs, material types, and window ratios.
+The main functionality includes:
+- Material ID mapping and retrieval
+- Window pattern generation based on configurable ratios
+- Building material assignment from GeoDataFrame data
+"""
+
 import numpy as np
 
 def get_material_dict():
     """
     Returns a dictionary mapping material names to their corresponding ID values.
+    
+    The material IDs use negative values to distinguish them from other voxel types.
+    Each material has a unique negative ID that can be used for material-based
+    rendering and analysis.
+    
+    Returns:
+        dict: Dictionary with material names as keys and negative integer IDs as values.
+              Available materials: unknown, brick, wood, concrete, metal, stone, glass, plaster
     """
     return {
         "unknown": -3,
@@ -19,23 +38,38 @@ def get_modulo_numbers(window_ratio):
     """
     Determines the appropriate modulo numbers for x, y, z based on window_ratio.
     
+    This function creates different window patterns by returning modulo values that
+    control the spacing of windows in the x, y, and z dimensions. Lower window_ratio
+    values result in sparser window patterns (higher modulo values), while higher
+    ratios create denser patterns.
+    
+    The function uses hash-based selection for certain ratios to introduce variety
+    in window patterns for buildings with similar window ratios.
+    
     Parameters:
-    window_ratio: float between 0 and 1.0
+        window_ratio (float): Value between 0 and 1.0 representing window density
     
     Returns:
-    tuple (x_mod, y_mod, z_mod): modulo numbers for each dimension
+        tuple: (x_mod, y_mod, z_mod) - modulo numbers for each dimension
+               Higher values = sparser windows, lower values = denser windows
     """
+    # Very sparse windows - every 2nd position in all dimensions
     if window_ratio <= 0.125 + 0.0625:  # around 0.125
         return (2, 2, 2)
+    # Medium-sparse windows - vary pattern across dimensions
     elif window_ratio <= 0.25 + 0.125:  # around 0.25
         combinations = [(2, 2, 1), (2, 1, 2), (1, 2, 2)]
+        # Use hash for consistent but varied selection
         return combinations[hash(str(window_ratio)) % len(combinations)]
+    # Medium density windows - two dimensions sparse, one dense
     elif window_ratio <= 0.5 + 0.125:  # around 0.5
         combinations = [(2, 1, 1), (1, 2, 1), (1, 1, 2)]
         return combinations[hash(str(window_ratio)) % len(combinations)]
+    # Dense windows - similar pattern to medium density
     elif window_ratio <= 0.75 + 0.125:  # around 0.75
         combinations = [(2, 1, 1), (1, 2, 1), (1, 1, 2)]
         return combinations[hash(str(window_ratio)) % len(combinations)]
+    # Maximum density - windows at every position
     else:  # above 0.875
         return (1, 1, 1)
 
@@ -44,64 +78,82 @@ def set_building_material_by_id(voxelcity_grid, building_id_grid_ori, ids, mark,
     Marks cells in voxelcity_grid based on building IDs and window ratio.
     Never sets glass_id to cells with maximum z index.
     
+    This function processes buildings by:
+    1. Finding all positions matching the specified building IDs
+    2. Setting the base material for all building voxels
+    3. Creating window patterns based on window_ratio and modulo calculations
+    4. Ensuring the top floor (maximum z) never gets windows (glass_id)
+    
+    The window pattern is determined by the modulo values returned from get_modulo_numbers(),
+    which creates different densities and arrangements of windows based on the window_ratio.
+    
     Parameters:
-    voxelcity_grid: 3D numpy array
-    building_id_grid_ori: 2D numpy array containing building IDs
-    ids: list/array of building IDs to check
-    mark: value to set for marked cells
-    window_ratio: float between 0 and 1.0, determines window density:
-        ~0.125: sparse windows (2,2,2)
-        ~0.25: medium-sparse windows (2,2,1), (2,1,2), or (1,2,2)
-        ~0.5: medium windows (2,1,1), (1,2,1), or (1,1,2)
-        ~0.75: dense windows (2,1,1), (1,2,1), or (1,1,2)
-        >0.875: maximum density (1,1,1)
-    glass_id: value to set for glass cells (default: -16)
+        voxelcity_grid (numpy.ndarray): 3D numpy array representing the voxel grid
+        building_id_grid_ori (numpy.ndarray): 2D numpy array containing building IDs
+        ids (list/array): Building IDs to process
+        mark (int): Material ID value to set for building cells
+        window_ratio (float): Value between 0 and 1.0 determining window density:
+            ~0.125: sparse windows (2,2,2)
+            ~0.25: medium-sparse windows (2,2,1), (2,1,2), or (1,2,2)
+            ~0.5: medium windows (2,1,1), (1,2,1), or (1,1,2)
+            ~0.75: dense windows (2,1,1), (1,2,1), or (1,1,2)
+            >0.875: maximum density (1,1,1)
+        glass_id (int): Material ID for glass/window cells (default: -16)
     
     Returns:
-    Modified voxelcity_grid
+        numpy.ndarray: Modified voxelcity_grid with building materials and windows applied
     """
+    # Flip the building ID grid vertically to match coordinate system
     building_id_grid = np.flipud(building_id_grid_ori.copy())
     
-    # Get modulo numbers based on window_ratio
+    # Get modulo numbers based on window_ratio for pattern generation
     x_mod, y_mod, z_mod = get_modulo_numbers(window_ratio)
     
-    # Get positions where building IDs match
+    # Find all positions where building IDs match the specified IDs
     building_positions = np.where(np.isin(building_id_grid, ids))
     
-    # Loop through each position that matches building IDs
+    # Process each building position
     for i in range(len(building_positions[0])):
         x, y = building_positions[0][i], building_positions[1][i]
+        
+        # Set base building material for all voxels at this x,y position
+        # Only modify voxels that are currently marked as "unknown" (-3)
         z_mask = voxelcity_grid[x, y, :] == -3
         voxelcity_grid[x, y, z_mask] = mark
         
-        # Check if x and y meet the modulo conditions
+        # Apply window pattern if position meets modulo conditions
         if x % x_mod == 0 and y % y_mod == 0:
+            # Find all z positions with the building material
             z_mask = voxelcity_grid[x, y, :] == mark
             if np.any(z_mask):
-                # Find the maximum z index where z_mask is True
+                # Get z indices and find the maximum (top floor)
                 z_indices = np.where(z_mask)[0]
                 max_z_index = np.max(z_indices)
                 
-                # Create base mask excluding maximum z index
+                # Create base mask excluding the top floor
+                # This ensures the roof never gets windows
                 base_mask = z_mask.copy()
                 base_mask[max_z_index] = False
                 
-                # Create pattern mask based on z modulo
+                # Create window pattern based on z modulo
                 pattern_mask = np.zeros_like(z_mask)
                 valid_z_indices = z_indices[z_indices != max_z_index]  # Exclude max_z_index
                 if len(valid_z_indices) > 0:
+                    # Apply z modulo pattern to create vertical window spacing
                     pattern_mask[valid_z_indices[valid_z_indices % z_mod == 0]] = True
                 
-                # For window_ratio around 0.75, add additional pattern
+                # For higher window ratios, add additional window pattern
+                # This creates denser window arrangements for buildings with more windows
                 if 0.625 < window_ratio <= 0.875 and len(valid_z_indices) > 0:
                     additional_pattern = np.zeros_like(z_mask)
                     additional_pattern[valid_z_indices[valid_z_indices % (z_mod + 1) == 0]] = True
+                    # Combine patterns using logical OR to increase window density
                     pattern_mask = np.logical_or(pattern_mask, additional_pattern)
                 
-                # Final mask combines base_mask and pattern_mask
+                # Combine base mask (excluding top floor) with pattern mask
                 final_glass_mask = np.logical_and(base_mask, pattern_mask)
                 
-                # Set glass_id for all positions in the final mask
+                # Set glass material for all positions matching the final mask
                 voxelcity_grid[x, y, final_glass_mask] = glass_id
     
     return voxelcity_grid
@@ -110,27 +162,42 @@ def set_building_material_by_gdf(voxelcity_grid_ori, building_id_grid, gdf_build
     """
     Sets building materials based on a GeoDataFrame containing building information.
     
+    This function iterates through a GeoDataFrame of building data and applies
+    materials and window patterns to the corresponding buildings in the voxel grid.
+    It handles missing material information by defaulting to 'unknown' material.
+    
     Parameters:
-    voxelcity_grid_ori: 3D numpy array of the original voxel grid
-    building_id_grid: 2D numpy array containing building IDs
-    gdf_buildings: GeoDataFrame containing building information with columns:
-                  'building_id', 'surface_material', 'window_ratio'
-    material_id_dict: Dictionary mapping material names to their IDs (optional)
+        voxelcity_grid_ori (numpy.ndarray): 3D numpy array of the original voxel grid
+        building_id_grid (numpy.ndarray): 2D numpy array containing building IDs
+        gdf_buildings (GeoDataFrame): Building information with required columns:
+                      'building_id': Unique identifier for each building
+                      'surface_material': Material type (brick, wood, concrete, etc.)
+                      'window_ratio': Float between 0-1 for window density
+        material_id_dict (dict, optional): Dictionary mapping material names to IDs.
+                                         If None, uses default from get_material_dict()
     
     Returns:
-    Modified voxelcity_grid
+        numpy.ndarray: Modified voxelcity_grid with all building materials and windows applied
     """
+    # Create a copy to avoid modifying the original grid
     voxelcity_grid = voxelcity_grid_ori.copy()
+    
+    # Use default material dictionary if none provided
     if material_id_dict == None:
         material_id_dict = get_material_dict()
 
+    # Process each building in the GeoDataFrame
     for index, row in gdf_buildings.iterrows():
-        # Access properties
+        # Extract building properties from the current row
         osmid = row['building_id']
         surface_material = row['surface_material']
         window_ratio = row['window_ratio']
+        
+        # Handle missing surface material data
         if surface_material is None:
-            surface_material = 'unknown'            
+            surface_material = 'unknown'
+        
+        # Apply material and window pattern to this building
         set_building_material_by_id(voxelcity_grid, building_id_grid, osmid, 
                                   material_id_dict[surface_material], 
                                   window_ratio=window_ratio,