voxcity 0.6.26__py3-none-any.whl → 1.0.2__py3-none-any.whl

voxcity/utils/classes.py

@@ -0,0 +1,194 @@
+"""
+VoxCity Class Definitions
+
+This module provides standard class definitions for voxel grid semantics
+and land cover classification used throughout VoxCity.
+
+Voxel Grid Semantics:
+    The 3D voxel grid uses integer codes to represent different urban elements.
+    Negative values represent structural elements, while positive values 
+    represent land cover classes at the ground surface layer.
+
+Land Cover Classes:
+    Land cover is standardized to a 1-based indexing system (1-14) for 
+    consistency across different data sources. This standard classification
+    is used in the voxel representation and exports.
+"""
+
+import numpy as np
+from typing import Dict, Optional
+
+
+# =============================================================================
+# Voxel Semantic Codes
+# =============================================================================
+
+VOXEL_CODES = {
+    -3: "Building",
+    -2: "Tree Canopy",
+    -1: "Ground/Subsurface",
+    # Positive values (>=1) represent land cover classes at ground surface
+}
+
+VOXEL_CODE_DESCRIPTIONS = """
+Voxel Grid Semantic Codes:
+  -3 : Building volume
+  -2 : Tree canopy (vegetation)
+  -1 : Ground/Subsurface
+  >=1: Land cover class at ground surface (see Land Cover Classes)
+"""
+
+
+# =============================================================================
+# Standard Land Cover Classes (1-based indices)
+# =============================================================================
+
+LAND_COVER_CLASSES = {
+    1: "Bareland",
+    2: "Rangeland",
+    3: "Shrub",
+    4: "Agriculture land",
+    5: "Tree",
+    6: "Moss and lichen",
+    7: "Wet land",
+    8: "Mangrove",
+    9: "Water",
+    10: "Snow and ice",
+    11: "Developed space",
+    12: "Road",
+    13: "Building",
+    14: "No Data",
+}
+
+LAND_COVER_DESCRIPTIONS = """
+VoxCity Standard Land Cover Classes (1-based indices, used in voxel grids):
+--------------------------------------------------
+   1: Bareland           - Bare soil, rocks, desert
+   2: Rangeland          - Grassland, pasture
+   3: Shrub              - Shrubland, bushes
+   4: Agriculture land   - Cropland, farmland
+   5: Tree               - Forest, tree cover
+   6: Moss and lichen    - Moss, lichen cover
+   7: Wet land           - Wetland, marsh
+   8: Mangrove           - Mangrove forest
+   9: Water              - Water bodies
+  10: Snow and ice       - Snow, ice, glaciers
+  11: Developed space    - Urban areas, parking
+  12: Road               - Roads, paved surfaces
+  13: Building           - Building footprints
+  14: No Data            - Missing or invalid data
+--------------------------------------------------
+Note: Source-specific land cover classes are converted to these
+      standard classes during voxelization.
+"""
+
+
+# =============================================================================
+# Print Helper Functions
+# =============================================================================
+
+def print_voxel_codes() -> None:
+    """Print voxel semantic codes to console."""
+    print(VOXEL_CODE_DESCRIPTIONS)
+
+
+def print_land_cover_classes() -> None:
+    """Print standard land cover class definitions to console."""
+    print(LAND_COVER_DESCRIPTIONS)
+
+
+def print_class_definitions() -> None:
+    """Print both voxel codes and land cover class definitions."""
+    print("\n" + "=" * 60)
+    print("VoxCity Class Definitions")
+    print("=" * 60)
+    print(VOXEL_CODE_DESCRIPTIONS)
+    print(LAND_COVER_DESCRIPTIONS)
+    print("=" * 60 + "\n")
+
+
+def get_land_cover_name(index: int) -> str:
+    """
+    Get the land cover class name for a given index.
+    
+    Args:
+        index: Land cover class index (1-14)
+        
+    Returns:
+        Class name string, or "Unknown" if index is invalid
+    """
+    return LAND_COVER_CLASSES.get(index, "Unknown")
+
+
+def get_voxel_code_name(code: int) -> str:
+    """
+    Get the semantic name for a voxel code.
+    
+    Args:
+        code: Voxel code (negative for structures, positive for land cover)
+        
+    Returns:
+        Semantic name string
+    """
+    if code in VOXEL_CODES:
+        return VOXEL_CODES[code]
+    elif code >= 1:
+        return f"Land Cover: {get_land_cover_name(code)}"
+    elif code == 0:
+        return "Empty/Air"
+    else:
+        return "Unknown"
+
+
+def summarize_voxel_grid(voxel_grid: np.ndarray, print_output: bool = True) -> Dict[int, int]:
+    """
+    Summarize the contents of a voxel grid.
+    
+    Args:
+        voxel_grid: 3D numpy array of voxel codes
+        print_output: Whether to print the summary
+        
+    Returns:
+        Dictionary mapping voxel codes to counts
+    """
+    unique, counts = np.unique(voxel_grid, return_counts=True)
+    summary = dict(zip(unique.tolist(), counts.tolist()))
+    
+    if print_output:
+        print("\nVoxel Grid Summary:")
+        print("-" * 40)
+        for code in sorted(summary.keys()):
+            name = get_voxel_code_name(code)
+            count = summary[code]
+            percentage = 100.0 * count / voxel_grid.size
+            print(f"  {code:4d}: {name:25s} - {count:,} voxels ({percentage:.2f}%)")
+        print("-" * 40)
+    
+    return summary
+
+
+def summarize_land_cover_grid(land_cover_grid: np.ndarray, print_output: bool = True) -> Dict[int, int]:
+    """
+    Summarize the contents of a land cover grid.
+    
+    Args:
+        land_cover_grid: 2D numpy array of land cover class indices
+        print_output: Whether to print the summary
+        
+    Returns:
+        Dictionary mapping class indices to counts
+    """
+    unique, counts = np.unique(land_cover_grid, return_counts=True)
+    summary = dict(zip(unique.tolist(), counts.tolist()))
+    
+    if print_output:
+        print("\nLand Cover Grid Summary:")
+        print("-" * 40)
+        for idx in sorted(summary.keys()):
+            name = get_land_cover_name(idx) if idx >= 1 else f"Source-specific ({idx})"
+            count = summary[idx]
+            percentage = 100.0 * count / land_cover_grid.size
+            print(f"  {idx:4d}: {name:25s} - {count:,} cells ({percentage:.2f}%)")
+        print("-" * 40)
+    
+    return summary

voxcity/utils/lc.py

@@ -34,21 +34,22 @@ def rgb_distance(color1, color2):
     return np.sqrt(np.sum((np.array(color1) - np.array(color2))**2))  
 
 
-# Legacy land cover classes mapping - kept for reference
+# Standard land cover classes mapping (1-based indices for voxel representation)
 # land_cover_classes = {
-#     (128, 0, 0): 'Bareland',              0         
-#     (0, 255, 36): 'Rangeland',            1
-#     (97, 140, 86): 'Shrub',               2
-#     (75, 181, 73): 'Agriculture land',    3
-#     (34, 97, 38): 'Tree',                 4
-#     (77, 118, 99): 'Wet land',            5
-#     (22, 61, 51): 'Mangrove',             6
-#     (0, 69, 255): 'Water',                7
-#     (205, 215, 224): 'Snow and ice',      8
-#     (148, 148, 148): 'Developed space',   9
-#     (255, 255, 255): 'Road',              10
-#     (222, 31, 7): 'Building',             11
-#     (128, 0, 0): 'No Data',               12
+#     (128, 0, 0): 'Bareland',              1         
+#     (0, 255, 36): 'Rangeland',            2
+#     (97, 140, 86): 'Shrub',               3
+#     (75, 181, 73): 'Agriculture land',    4
+#     (34, 97, 38): 'Tree',                 5
+#     (255, 255, 0): 'Moss and lichen',     6
+#     (77, 118, 99): 'Wet land',            7
+#     (22, 61, 51): 'Mangrove',             8
+#     (0, 69, 255): 'Water',                9
+#     (205, 215, 224): 'Snow and ice',      10
+#     (148, 148, 148): 'Developed space',   11
+#     (255, 255, 255): 'Road',              12
+#     (222, 31, 7): 'Building',             13
+#     (128, 0, 0): 'No Data',               14
 # }
 
 def get_land_cover_classes(source):
@@ -161,22 +162,58 @@ def get_land_cover_classes(source):
         }
     return land_cover_classes
 
-# Legacy land cover classes with numeric indices - kept for reference
+
+def get_source_class_descriptions(source):
+    """
+    Get a formatted string describing land cover classes for a specific source.
+    
+    Args:
+        source (str): Name of the land cover data source.
+        
+    Returns:
+        str: Formatted string describing the source's land cover classes.
+    """
+    land_cover_classes = get_land_cover_classes(source)
+    # Get unique class names (values from the dict)
+    class_names = list(dict.fromkeys(land_cover_classes.values()))
+    
+    lines = [f"\n{source} Land Cover Classes (source-specific, 0-based indices):"]
+    lines.append("-" * 55)
+    for idx, name in enumerate(class_names):
+        lines.append(f"  {idx:2d}: {name}")
+    lines.append("-" * 55)
+    
+    # Special note for OpenStreetMap/Standard which uses same class names
+    if source in ("OpenStreetMap", "Standard"):
+        lines.append("Note: OpenStreetMap uses VoxCity Standard class names.")
+        lines.append("      Indices shift from 0-based to 1-based during voxelization.")
+    else:
+        lines.append("Note: These source-specific classes will be converted to")
+        lines.append("      VoxCity Standard Classes (1-14) during voxelization.")
+    
+    lines.append("")
+    lines.append("Access 2D land cover grid from VoxCity object:")
+    lines.append("  land_cover_grid = voxcity.land_cover.classes")
+    lines.append("")
+    return "\n".join(lines)
+
+
+# Standard land cover classes with numeric indices (1-based for voxel representation)
 # land_cover_classes = {
-#     (128, 0, 0): 'Bareland',              0         
-#     (0, 255, 36): 'Rangeland',            1
-#     (97, 140, 86): 'Shrub',               2
-#     (75, 181, 73): 'Agriculture land',    3
-#     (34, 97, 38): 'Tree',                 4
-#     (34, 97, 38): 'Moss and lichen',      5
-#     (77, 118, 99): 'Wet land',            6
-#     (22, 61, 51): 'Mangrove',             7
-#     (0, 69, 255): 'Water',                8
-#     (205, 215, 224): 'Snow and ice',      9
-#     (148, 148, 148): 'Developed space',   10
-#     (255, 255, 255): 'Road',              11
-#     (222, 31, 7): 'Building',             12
-#     (128, 0, 0): 'No Data',               13
+#     (128, 0, 0): 'Bareland',              1         
+#     (0, 255, 36): 'Rangeland',            2
+#     (97, 140, 86): 'Shrub',               3
+#     (75, 181, 73): 'Agriculture land',    4
+#     (34, 97, 38): 'Tree',                 5
+#     (255, 255, 0): 'Moss and lichen',     6
+#     (77, 118, 99): 'Wet land',            7
+#     (22, 61, 51): 'Mangrove',             8
+#     (0, 69, 255): 'Water',                9
+#     (205, 215, 224): 'Snow and ice',      10
+#     (148, 148, 148): 'Developed space',   11
+#     (255, 255, 255): 'Road',              12
+#     (222, 31, 7): 'Building',             13
+#     (128, 0, 0): 'No Data',               14
 # }
 
 
@@ -185,21 +222,23 @@ def convert_land_cover(input_array, land_cover_source='Urbanwatch'):
     """
     Optimized version using direct numpy array indexing instead of np.vectorize.
     This is 10-100x faster than the original.
+    
+    Returns 1-based class indices (1-14) for consistency with voxel representations.
     """
-    # Define mappings
+    # Define mappings (1-based indices: 1=Bareland, 2=Rangeland, ..., 14=No Data)
     if land_cover_source == 'Urbanwatch':
-        mapping = {0: 12, 1: 11, 2: 10, 3: 4, 4: 1, 5: 3, 6: 8, 7: 0, 8: 13, 9: 8}
+        mapping = {0: 13, 1: 12, 2: 11, 3: 5, 4: 2, 5: 4, 6: 9, 7: 1, 8: 14, 9: 9}
     elif land_cover_source == 'ESA WorldCover':
-        mapping = {0: 4, 1: 2, 2: 1, 3: 3, 4: 10, 5: 0, 6: 9, 7: 8, 8: 6, 9: 7, 10: 5}
+        mapping = {0: 5, 1: 3, 2: 2, 3: 4, 4: 11, 5: 1, 6: 10, 7: 9, 8: 7, 9: 8, 10: 6}
     elif land_cover_source == "ESRI 10m Annual Land Cover":
-        mapping = {0: 13, 1: 8, 2: 4, 3: 1, 4: 6, 5: 3, 6: 2, 7: 10, 8: 0, 9: 9, 10: 13}
+        mapping = {0: 14, 1: 9, 2: 5, 3: 2, 4: 7, 5: 4, 6: 3, 7: 11, 8: 1, 9: 10, 10: 14}
     elif land_cover_source == "Dynamic World V1":
-        mapping = {0: 8, 1: 4, 2: 1, 3: 6, 4: 3, 5: 2, 6: 10, 7: 0, 8: 9}    
+        mapping = {0: 9, 1: 5, 2: 2, 3: 7, 4: 4, 5: 3, 6: 11, 7: 1, 8: 10}    
     elif land_cover_source == "OpenEarthMapJapan":
-        mapping = {0: 0, 1: 1, 2: 10, 3: 11, 4: 4, 5: 8, 6: 3, 7: 12}
+        mapping = {0: 1, 1: 2, 2: 11, 3: 12, 4: 5, 5: 9, 6: 4, 7: 13}
     else:
-        # If unknown source, return as-is
-        return input_array.copy()
+        # If unknown source, return as-is with +1 offset for consistency
+        return input_array.copy() + 1
     
     # Create a full mapping array for all possible values (0-255 for uint8)
     max_val = max(max(mapping.keys()), input_array.max()) + 1
@@ -374,12 +413,14 @@ def convert_land_cover_array(input_array, land_cover_classes):
         land_cover_classes (dict): Dictionary mapping RGB tuples to class names
         
     Returns:
-        numpy.ndarray: Array with integer indices corresponding to land cover classes
+        numpy.ndarray: Array with 0-based integer indices corresponding to land cover classes
         
     Note:
         Classes not found in the mapping are assigned index -1
+        Indices are 0-based as source-specific indices. Use convert_land_cover() to 
+        remap to standard 1-based indices for voxel representation.
     """
-    # Create a mapping of class names to integers
+    # Create a mapping of class names to integers (0-based, source-specific order)
     class_to_int = {name: i for i, name in enumerate(land_cover_classes.values())}
 
     # Create a vectorized function to map string values to integers

voxcity/utils/logging.py

@@ -0,0 +1,61 @@
+"""
+Lightweight, centralized logging utilities for the voxcity package.
+
+Usage:
+    from voxcity.utils.logging import get_logger
+    logger = get_logger(__name__)
+
+Environment variables:
+    VOXCITY_LOG_LEVEL: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+
+_LEVEL_NAMES = {
+    "CRITICAL": logging.CRITICAL,
+    "ERROR": logging.ERROR,
+    "WARNING": logging.WARNING,
+    "INFO": logging.INFO,
+    "DEBUG": logging.DEBUG,
+}
+
+
+def _resolve_level(env_value: Optional[str]) -> int:
+    if not env_value:
+        return logging.INFO
+    return _LEVEL_NAMES.get(env_value.strip().upper(), logging.INFO)
+
+
+def _configure_root_once() -> None:
+    root = logging.getLogger("voxcity")
+    if root.handlers:
+        return
+    level = _resolve_level(os.getenv("VOXCITY_LOG_LEVEL"))
+    root.setLevel(level)
+    handler = logging.StreamHandler()
+    handler.setLevel(level)
+    formatter = logging.Formatter(
+        fmt="%(levelname)s | %(name)s | %(message)s",
+    )
+    handler.setFormatter(formatter)
+    root.addHandler(handler)
+    # Prevent duplicate messages from propagating to the global root logger
+    root.propagate = False
+
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    """Return a child logger under the package root logger.
+
+    - Ensures a single configuration for the package
+    - Respects VOXCITY_LOG_LEVEL if set
+    """
+    _configure_root_once()
+    pkg_logger = logging.getLogger("voxcity")
+    return pkg_logger.getChild(name) if name else pkg_logger
+
+

voxcity/utils/orientation.py

@@ -0,0 +1,51 @@
+"""Grid orientation helpers.
+
+Contract:
+- Canonical internal orientation is "north_up": row 0 is the northern/top row,
+  increasing row index moves south/down. Columns increase eastward: column 0 is
+  west/left and indices increase toward the east/right. All processing functions
+  accept and return 2D grids in this orientation unless explicitly documented
+  otherwise.
+- Visualization utilities may flip vertically for display purposes only.
+- 3D indexing follows (row, col, z) = (north→south, west→east, ground→up).
+
+Utilities here are intentionally minimal to avoid introducing hidden behavior.
+They can be used at I/O boundaries (e.g., when reading rasters with south_up
+conventions) to normalize to the internal orientation.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+import numpy as np
+
+# Public constants to reference orientation in docs and code
+ORIENTATION_NORTH_UP: Literal["north_up"] = "north_up"
+ORIENTATION_SOUTH_UP: Literal["south_up"] = "south_up"
+
+
+def ensure_orientation(
+    grid: np.ndarray,
+    orientation_in: Literal["north_up", "south_up"],
+    orientation_out: Literal["north_up", "south_up"] = ORIENTATION_NORTH_UP,
+) -> np.ndarray:
+    """Return ``grid`` converted from ``orientation_in`` to ``orientation_out``.
+
+    Both orientations are defined for 2D arrays as:
+    - north_up: row 0 = north/top, last row = south/bottom
+    - south_up: row 0 = south/bottom, last row = north/top
+
+    If orientations match, the input array is returned unchanged. When converting
+    between north_up and south_up, a vertical flip is applied using ``np.flipud``.
+
+    Notes
+    -----
+    - This function does not copy when no conversion is needed.
+    - Use at data boundaries (read/write, interop) rather than deep in processing code.
+    """
+    if orientation_in == orientation_out:
+        return grid
+    # Only two orientations supported; converting between them is a vertical flip
+    return np.flipud(grid)
+
+