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

voxcity/downloader/omt.py

@@ -4,6 +4,21 @@ Module for downloading and processing building data from OpenMapTiles vector til
 This module provides functionality to download and process building footprint data from
 OpenMapTiles vector tile service. It handles downloading PBF tiles, extracting building
 geometries, and converting them to GeoJSON format with standardized properties.
+
+Key Features:
+    - Downloads vector tiles from OpenMapTiles API
+    - Extracts building footprints and properties
+    - Converts coordinates from tile-local to WGS84
+    - Standardizes building height information
+    - Handles both Polygon and MultiPolygon geometries
+    - Separates inner and outer rings of building footprints
+
+Dependencies:
+    - mercantile: For tile calculations and coordinate transformations
+    - mapbox_vector_tile: For decoding PBF vector tiles
+    - shapely: For geometry operations
+    - pyproj: For coordinate system transformations
+    - geopandas: For working with geospatial data
 """
 
 import mercantile
@@ -16,15 +31,33 @@ import json
 from pyproj import Transformer
 import json
 import geopandas as gpd
+
 def load_gdf_from_openmaptiles(rectangle_vertices, API_KEY):
     """Download and process building footprint data from OpenMapTiles vector tiles.
 
+    This function downloads vector tiles covering the specified area, extracts building
+    footprints, and converts them to a standardized format in a GeoDataFrame.
+
     Args:
-        rectangle_vertices: List of (lon, lat) coordinates defining the bounding box
-        API_KEY: OpenMapTiles API key for authentication
+        rectangle_vertices (list): List of (lon, lat) tuples defining the bounding box corners.
+            The coordinates should be in WGS84 (EPSG:4326) format.
+        API_KEY (str): OpenMapTiles API key for authentication. Must be valid for the v3 endpoint.
 
     Returns:
-        geopandas.GeoDataFrame: GeoDataFrame containing building footprints with standardized properties
+        geopandas.GeoDataFrame: A GeoDataFrame containing building footprints with the following columns:
+            - geometry: Building footprint geometry in WGS84 coordinates
+            - height: Building height in meters
+            - min_height: Minimum height (e.g., for elevated structures) in meters
+            - confidence: Confidence score (-1.0 for OpenMapTiles data)
+            - is_inner: Boolean indicating if the polygon is an inner ring
+            - role: String indicating 'inner' or 'outer' ring
+            - id: Unique identifier for each building feature
+
+    Notes:
+        - Uses zoom level 15 for optimal detail vs data size balance
+        - Converts coordinates from Web Mercator (EPSG:3857) to WGS84 (EPSG:4326)
+        - Handles both Polygon and MultiPolygon geometries
+        - Separates complex building footprints into their constituent parts
     """
     # Extract longitudes and latitudes from vertices to find bounding box
     lons = [coord[0] for coord in rectangle_vertices]
@@ -124,11 +157,26 @@ def load_gdf_from_openmaptiles(rectangle_vertices, API_KEY):
 def get_height_from_properties(properties):
     """Extract building height from properties, using levels if height is not available.
 
+    This function implements a fallback strategy for determining building heights:
+    1. First tries to use explicit render_height property
+    2. If not available, estimates height from number of building levels
+    3. Returns 0 if no valid height information is found
+
     Args:
-        properties: Dictionary containing building properties
+        properties (dict): Dictionary containing building properties from OpenMapTiles.
+            Expected keys:
+            - render_height: Direct height specification in meters
+            - building:levels: Number of building floors/levels
 
     Returns:
-        float: Building height in meters, defaults to 0 if no valid height found
+        float: Building height in meters. Values can be:
+            - Explicit height from render_height property
+            - Estimated height (levels * 5.0 meters per level)
+            - 0.0 if no valid height information is found
+
+    Notes:
+        - Assumes average floor height of 5 meters when estimating from levels
+        - Handles potential invalid values gracefully by returning 0
     """
     # First try explicit render_height property
     height = properties.get('render_height')
@@ -152,11 +200,30 @@ def get_height_from_properties(properties):
 def convert_geojson_format(features):
     """Convert building features to standardized format with height information.
 
+    This function processes raw OpenMapTiles building features into a standardized format,
+    handling complex geometries and adding consistent property attributes.
+
     Args:
-        features: List of GeoJSON features containing building footprints
+        features (list): List of GeoJSON features containing building footprints.
+            Each feature should have:
+            - geometry: GeoJSON geometry (Polygon or MultiPolygon)
+            - properties: Dictionary of building properties
 
     Returns:
-        list: List of standardized GeoJSON features with height properties
+        list: List of standardized GeoJSON features where:
+            - Complex MultiPolygons are split into individual Polygons
+            - Each Polygon ring (outer and inner) becomes a separate feature
+            - Properties are standardized to include:
+                - height: Building height in meters
+                - min_height: Minimum height in meters
+                - confidence: Set to -1.0 for OpenMapTiles data
+                - is_inner: Boolean flag for inner rings
+                - role: String indicating 'inner' or 'outer' ring
+
+    Notes:
+        - Preserves coordinate order as (longitude, latitude)
+        - Maintains topological relationships through is_inner and role properties
+        - Splits complex geometries for easier processing downstream
     """
     new_features = []
 

voxcity/downloader/osm.py

@@ -4,6 +4,13 @@ Module for downloading and processing OpenStreetMap data.
 This module provides functionality to download and process building footprints, land cover,
 and other geographic features from OpenStreetMap. It handles downloading data via the Overpass API,
 processing the responses, and converting them to standardized GeoJSON format with proper properties.
+
+The module includes functions for:
+- Converting OSM JSON to GeoJSON format
+- Processing building footprints with height information
+- Handling land cover classifications
+- Managing coordinate systems and projections
+- Processing roads and other geographic features
 """
 
 import requests
@@ -174,7 +181,15 @@ def osm_json_to_geojson(osm_data):
     }
 
 def is_part_of_relation(way_id, osm_data):
-    """Check if a way is part of any relation."""
+    """Check if a way is part of any relation in the OSM data.
+    
+    Args:
+        way_id (int): The ID of the way to check
+        osm_data (dict): OSM JSON data containing elements
+        
+    Returns:
+        bool: True if the way is part of a relation, False otherwise
+    """
     for element in osm_data['elements']:
         if element['type'] == 'relation' and 'members' in element:
             for member in element['members']:
@@ -183,7 +198,18 @@ def is_part_of_relation(way_id, osm_data):
     return False
 
 def is_way_polygon(way):
-    """Determine if a way should be treated as a polygon."""
+    """Determine if a way should be treated as a polygon based on OSM tags and geometry.
+    
+    A way is considered a polygon if:
+    1. It forms a closed loop (first and last nodes are the same)
+    2. It has tags indicating it represents an area (building, landuse, etc.)
+    
+    Args:
+        way (dict): OSM way element with nodes and tags
+        
+    Returns:
+        bool: True if the way should be treated as a polygon, False otherwise
+    """
     # Check if the way is closed (first and last nodes are the same)
     if 'nodes' in way and way['nodes'][0] == way['nodes'][-1]:
         # Check for tags that indicate this is an area
@@ -196,7 +222,16 @@ def is_way_polygon(way):
     return False
 
 def get_way_coords(way, nodes):
-    """Get coordinates for a way."""
+    """Extract coordinates for a way from its node references.
+    
+    Args:
+        way (dict): OSM way element containing node references
+        nodes (dict): Dictionary mapping node IDs to their coordinates
+        
+    Returns:
+        list: List of coordinate pairs [(lon, lat), ...] for the way,
+             or empty list if any nodes are missing
+    """
     coords = []
     if 'nodes' not in way:
         return coords
@@ -211,16 +246,22 @@ def get_way_coords(way, nodes):
     return coords
 
 def create_rings_from_ways(way_ids, ways, nodes):
-    """
-    Create continuous rings by connecting ways.
+    """Create continuous rings by connecting ways that share nodes.
+    
+    This function handles complex relations by:
+    1. Connecting ways that share end nodes
+    2. Handling reversed way directions
+    3. Closing rings when possible
+    4. Converting node references to coordinates
     
     Args:
-        way_ids: List of way IDs that make up the ring(s)
-        ways: Dictionary mapping way IDs to way elements
-        nodes: Dictionary mapping node IDs to coordinates
+        way_ids (list): List of way IDs that make up the ring(s)
+        ways (dict): Dictionary mapping way IDs to way elements
+        nodes (dict): Dictionary mapping node IDs to coordinates
         
     Returns:
-        List of rings, where each ring is a list of coordinates
+        list: List of rings, where each ring is a list of coordinate pairs [(lon, lat), ...]
+              forming a closed polygon with at least 4 points
     """
     if not way_ids:
         return []
@@ -332,11 +373,23 @@ def create_rings_from_ways(way_ids, ways, nodes):
 def load_gdf_from_openstreetmap(rectangle_vertices):
     """Download and process building footprint data from OpenStreetMap.
     
+    This function:
+    1. Downloads building data using the Overpass API
+    2. Processes complex relations and their members
+    3. Extracts height information and other properties
+    4. Converts features to a GeoDataFrame with standardized properties
+    
     Args:
-        rectangle_vertices: List of (lon, lat) coordinates defining the bounding box
+        rectangle_vertices (list): List of (lon, lat) coordinates defining the bounding box
         
     Returns:
-        geopandas.GeoDataFrame: GeoDataFrame containing building footprints with standardized properties
+        geopandas.GeoDataFrame: GeoDataFrame containing building footprints with properties:
+            - geometry: Polygon or MultiPolygon
+            - height: Building height in meters
+            - levels: Number of building levels
+            - min_height: Minimum height (for elevated structures)
+            - building_type: Type of building
+            - And other OSM tags as properties
     """
     # Create a bounding box from the rectangle vertices
     min_lon = min(v[0] for v in rectangle_vertices)
@@ -533,13 +586,23 @@ def load_gdf_from_openstreetmap(rectangle_vertices):
     return gdf
 
 def convert_feature(feature):
-    """Convert a GeoJSON feature to the desired format with height information.
+    """Convert a GeoJSON feature to a standardized format with height information.
+    
+    This function:
+    1. Handles both Polygon and MultiPolygon geometries
+    2. Extracts and validates height information
+    3. Ensures coordinate order consistency (lon, lat)
+    4. Adds confidence scores for height estimates
     
     Args:
-        feature (dict): Input GeoJSON feature
+        feature (dict): Input GeoJSON feature with geometry and properties
         
     Returns:
-        dict: Converted feature with height and confidence values, or None if invalid
+        dict: Converted feature with:
+            - Standardized geometry (always Polygon)
+            - Height information in properties
+            - Confidence score for height values
+            Or None if the feature is invalid or not a polygon
     """
     new_feature = {}
     new_feature['type'] = 'Feature'
@@ -736,13 +799,21 @@ tag_osm_key_value_mapping = {
 }
 
 def get_classification(tags):
-    """Determine the classification code and name for a feature based on its OSM tags.
+    """Determine the land cover/use classification based on OSM tags.
+    
+    This function maps OSM tags to standardized land cover classes using:
+    1. A hierarchical classification system (codes 0-13)
+    2. Tag matching patterns for different feature types
+    3. Special cases for roads, water bodies, etc.
     
     Args:
-        tags (dict): Dictionary of OSM tags
+        tags (dict): Dictionary of OSM tags (key-value pairs)
         
     Returns:
-        tuple: (classification_code, classification_name) or (None, None) if no match
+        tuple: (classification_code, classification_name) where:
+            - classification_code (int): Numeric code (0-13) for the land cover class
+            - classification_name (str): Human-readable name of the class
+            Or (None, None) if no matching classification is found
     """
     # Iterate through each classification code and its associated info
     for code, info in classification_mapping.items():
@@ -764,13 +835,18 @@ def get_classification(tags):
     return None, None
 
 def swap_coordinates(geom_mapping):
-    """Swap coordinates from (lon, lat) to (lat, lon) order.
+    """Swap coordinate order in a GeoJSON geometry object.
+    
+    This function:
+    1. Handles nested coordinate structures (Polygons, MultiPolygons)
+    2. Preserves the original coordinate order if already correct
+    3. Works recursively for complex geometries
     
     Args:
-        geom_mapping (dict): GeoJSON geometry object
+        geom_mapping (dict): GeoJSON geometry object with coordinates
         
     Returns:
-        dict: Geometry with swapped coordinates
+        dict: Geometry with coordinates in the correct order (lon, lat)
     """
     coords = geom_mapping['coordinates']
 
@@ -786,13 +862,23 @@ def swap_coordinates(geom_mapping):
     return geom_mapping
 
 def load_land_cover_gdf_from_osm(rectangle_vertices_ori):
-    """Load land cover data from OpenStreetMap within a given rectangular area.
+    """Load and classify land cover data from OpenStreetMap.
+    
+    This function:
+    1. Downloads land cover features using the Overpass API
+    2. Classifies features based on OSM tags
+    3. Handles special cases like roads with width information
+    4. Projects geometries for accurate buffering
+    5. Creates a standardized GeoDataFrame with classifications
     
     Args:
-        rectangle_vertices_ori (list): List of (lon, lat) coordinates defining the rectangle
+        rectangle_vertices_ori (list): List of (lon, lat) coordinates defining the area
         
     Returns:
-        GeoDataFrame: GeoDataFrame containing land cover classifications
+        geopandas.GeoDataFrame: GeoDataFrame with:
+            - geometry: Polygon or MultiPolygon features
+            - class: Land cover classification name
+            - Additional properties from OSM tags
     """
     # Close the rectangle polygon by adding first vertex at the end
     rectangle_vertices = rectangle_vertices_ori.copy()

voxcity/downloader/overture.py

@@ -3,6 +3,18 @@ Module for downloading and processing building footprint data from Overture Maps
 
 This module provides functionality to download and process building footprints,
 handling the conversion of Overture Maps data to GeoJSON format with standardized properties.
+
+The module includes functions for:
+- Converting data types between numpy and Python native types
+- Processing and validating building footprint data
+- Handling geometric operations and coordinate transformations
+- Combining and standardizing building data from multiple sources
+
+Main workflow:
+1. Download building data from Overture Maps using a bounding box
+2. Process and standardize the data format
+3. Combine building and building part data
+4. Add unique identifiers and standardize properties
 """
 
 from overturemaps import core
@@ -15,11 +27,26 @@ def convert_numpy_to_python(obj):
     """
     Recursively convert numpy types to native Python types.
     
+    This function handles various numpy data types and complex nested structures,
+    ensuring all data is converted to Python native types for JSON serialization.
+    
     Args:
-        obj: Object to convert, can be dict, list, tuple, numpy type or other
+        obj: Object to convert, can be:
+            - dict: Dictionary with potentially nested numpy types
+            - list/tuple: Sequence with potentially nested numpy types
+            - numpy.ndarray: Numpy array to be converted to list
+            - numpy.integer/numpy.floating: Numpy numeric types
+            - native Python types (bool, str, int, float)
+            - None values
         
     Returns:
-        Converted object with numpy types replaced by native Python types
+        object: Converted object with all numpy types replaced by native Python types
+        
+    Examples:
+        >>> convert_numpy_to_python(np.int64(42))
+        42
+        >>> convert_numpy_to_python({'a': np.array([1, 2, 3])})
+        {'a': [1, 2, 3]}
     """
     # Handle dictionary case - recursively convert all values
     if isinstance(obj, dict):
@@ -50,11 +77,21 @@ def is_valid_value(value):
     """
     Check if a value is valid (not NA/null) and handle array-like objects.
     
+    This function is used to validate data before processing, ensuring that
+    null/NA values are handled appropriately while preserving array-like structures.
+    
     Args:
-        value: Value to check
+        value: Value to check, can be:
+            - numpy.ndarray: Always considered valid
+            - list: Always considered valid
+            - scalar values: Checked for NA/null status
         
     Returns:
         bool: True if value is valid (not NA/null or is array-like), False otherwise
+        
+    Note:
+        Arrays and lists are always considered valid since they may contain
+        valid data that needs to be processed individually.
     """
     # Arrays and lists are always considered valid since they may contain valid data
     if isinstance(value, (np.ndarray, list)):
@@ -65,14 +102,32 @@ def is_valid_value(value):
 def convert_gdf_to_geojson(gdf):
     """
     Convert GeoDataFrame to GeoJSON format with coordinates in (lon, lat) order.
-    Extracts all columns as properties except for 'geometry' and 'bbox'.
-    Sets height and min_height to 0 if not present and handles arrays.
+    
+    This function processes a GeoDataFrame containing building data and converts it
+    to a standardized GeoJSON format. It handles special cases for height values
+    and ensures all properties are properly converted to JSON-serializable types.
     
     Args:
-        gdf (GeoDataFrame): Input GeoDataFrame to convert
+        gdf (GeoDataFrame): Input GeoDataFrame containing building data with columns:
+            - geometry: Shapely geometry objects
+            - height: Building height (optional)
+            - min_height: Minimum building height (optional)
+            - Additional property columns
         
     Returns:
-        list: List of GeoJSON feature dictionaries
+        list: List of GeoJSON feature dictionaries, each containing:
+            - type: Always "Feature"
+            - properties: Dictionary of building properties including:
+                - height: Building height (defaults to 0.0)
+                - min_height: Minimum height (defaults to 0.0)
+                - id: Sequential unique identifier
+                - All other columns from input GeoDataFrame
+            - geometry: GeoJSON geometry object
+            
+    Note:
+        - Height values default to 0.0 if missing or invalid
+        - All numpy types are converted to native Python types
+        - Sequential IDs are assigned starting from 1
     """
     features = []
     id_count = 1
@@ -117,14 +172,22 @@ def convert_gdf_to_geojson(gdf):
 
 def rectangle_to_bbox(vertices):
     """
-    Convert rectangle vertices in (lon, lat) format to a GeoDataFrame bbox
-    with Shapely box geometry in (minx, miny, maxx, maxy) format
+    Convert rectangle vertices in (lon, lat) format to a bounding box.
+    
+    This function takes a list of coordinate pairs defining a rectangle and
+    converts them to a bounding box format required by the Overture Maps API.
     
     Args:
         vertices (list): List of tuples containing (lon, lat) coordinates
+            defining the corners of a rectangle
         
     Returns:
-        tuple: Bounding box coordinates (min_lon, min_lat, max_lon, max_lat)
+        tuple: Bounding box coordinates in format (min_lon, min_lat, max_lon, max_lat)
+            suitable for use with Overture Maps API
+            
+    Note:
+        The function calculates the minimum and maximum coordinates to ensure
+        the bounding box encompasses all provided vertices.
     """
     # Extract lon, lat values from vertices
     lons = [vertex[0] for vertex in vertices]
@@ -141,14 +204,26 @@ def rectangle_to_bbox(vertices):
 
 def join_gdfs_vertically(gdf1, gdf2):
     """
-    Join two GeoDataFrames vertically, handling different columns.
+    Join two GeoDataFrames vertically, handling different column structures.
+    
+    This function combines two GeoDataFrames that may have different columns,
+    ensuring all columns from both datasets are preserved in the output.
+    It provides diagnostic information about the combining process.
     
     Args:
-        gdf1 (GeoDataFrame): First GeoDataFrame
-        gdf2 (GeoDataFrame): Second GeoDataFrame
+        gdf1 (GeoDataFrame): First GeoDataFrame (e.g., buildings)
+        gdf2 (GeoDataFrame): Second GeoDataFrame (e.g., building parts)
         
     Returns:
-        GeoDataFrame: Combined GeoDataFrame with all columns from both inputs
+        GeoDataFrame: Combined GeoDataFrame containing:
+            - All rows from both input GeoDataFrames
+            - All columns from both inputs (filled with None where missing)
+            - Preserved geometry column
+            
+    Note:
+        - Prints diagnostic information about column differences
+        - Handles missing columns by filling with None values
+        - Preserves the geometry column for spatial operations
     """
     # Print diagnostic information about column differences
     print("GDF1 columns:", list(gdf1.columns))
@@ -183,26 +258,36 @@ def load_gdf_from_overture(rectangle_vertices):
     """
     Download and process building footprint data from Overture Maps.
     
+    This function serves as the main entry point for downloading building data.
+    It handles the complete workflow of downloading both building and building
+    part data, combining them, and preparing them for further processing.
+    
     Args:
-        rectangle_vertices (list): List of (lon, lat) coordinates defining the bounding box
+        rectangle_vertices (list): List of (lon, lat) coordinates defining
+            the bounding box for data download
         
     Returns:
-        list: List of GeoJSON features containing building footprints with standardized properties
+        GeoDataFrame: Combined dataset containing:
+            - Building and building part geometries
+            - Standardized properties
+            - Sequential numeric IDs
+            
+    Note:
+        - Downloads both building and building_part data from Overture Maps
+        - Combines the datasets while preserving all properties
+        - Assigns sequential IDs based on the final dataset index
     """
-    # Convert vertices to bounding box format required by Overture Maps
+    # Convert input vertices to Overture Maps API bounding box format
     bbox = rectangle_to_bbox(rectangle_vertices)
 
-    # Download building and building part data from Overture Maps
+    # Download primary building footprints and additional building part data
     building_gdf = core.geodataframe("building", bbox=bbox)
     building_part_gdf = core.geodataframe("building_part", bbox=bbox)
     
-    # Combine building and building part data into single dataset
+    # Combine both datasets into a single comprehensive building dataset
     joined_building_gdf = join_gdfs_vertically(building_gdf, building_part_gdf)
 
-    # # Convert combined dataset to GeoJSON format
-    # geojson_features = convert_gdf_to_geojson(joined_building_gdf)
-
-    # Replace id column with index numbers
+    # Assign sequential IDs based on the final dataset index
     joined_building_gdf['id'] = joined_building_gdf.index
 
     return joined_building_gdf

voxcity/downloader/utils.py

@@ -1,21 +1,36 @@
+# Utility functions for downloading files from various sources
 import requests
 import gdown
 
 def download_file(url, filename):
     """Download a file from a URL and save it locally.
     
+    This function uses the requests library to download a file from any publicly 
+    accessible URL and save it to the local filesystem. It handles the download 
+    process and provides feedback on the operation's success or failure.
+    
     Args:
-        url (str): URL of the file to download
-        filename (str): Local path where the downloaded file will be saved
+        url (str): URL of the file to download. Must be a valid, accessible URL.
+        filename (str): Local path where the downloaded file will be saved.
+                       Include the full path and filename with extension.
         
     Returns:
         None
         
     Prints:
-        Success or failure message with status code
+        - Success message with filename if download is successful (status code 200)
+        - Error message with status code if download fails
+        
+    Example:
+        >>> download_file('https://example.com/file.pdf', 'local_file.pdf')
+        File downloaded successfully and saved as local_file.pdf
     """
+    # Attempt to download the file from the provided URL
     response = requests.get(url)
+    
+    # Check if the download was successful (HTTP status code 200)
     if response.status_code == 200:
+        # Open the local file in binary write mode and save the content
         with open(filename, 'wb') as file:
             file.write(response.content)
         print(f"File downloaded successfully and saved as {filename}")
@@ -25,18 +40,33 @@ def download_file(url, filename):
 def download_file_google_drive(file_id, output_path):
     """Download a file from Google Drive using its file ID.
     
+    This function specifically handles downloads from Google Drive using the gdown
+    library, which is designed to bypass Google Drive's download restrictions.
+    It's useful for downloading large files or files that require authentication.
+    
     Args:
-        file_id (str): Google Drive file ID
-        output_path (str): Local path where the downloaded file will be saved
+        file_id (str): Google Drive file ID. This is the unique identifier in the 
+                       sharing URL after '/d/' or 'id='.
+        output_path (str): Local path where the downloaded file will be saved.
+                          Include the full path and filename with extension.
         
     Returns:
-        bool: True if download successful, False otherwise
+        bool: True if download was successful, False if any error occurred
         
     Prints:
-        Error message if download fails
+        Error message with exception details if download fails
+        
+    Example:
+        >>> success = download_file_google_drive('1234abcd...', 'downloaded_file.zip')
+        >>> if success:
+        >>>     print("Download completed successfully")
     """
+    # Construct the direct download URL using the file ID
     url = f"https://drive.google.com/uc?id={file_id}"
+    
     try:
+        # Use gdown to handle the Google Drive download
+        # quiet=False enables download progress display
         gdown.download(url, output_path, quiet=False)
         return True
     except Exception as e: