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

voxcity/geoprocessor/__init__.py

@@ -1,6 +1,75 @@
-from .draw import *
-from .grid import *
-from .utils import *
-from .network import *
-from .polygon import *
-from .mesh import *
+from . import (
+    draw,
+    utils,
+    network,
+    mesh,
+    raster,
+    conversion,
+    io,
+    heights,
+    selection,
+    overlap,
+    merge_utils,
+)
+
+# Re-export frequently used functions at package level for convenience
+from .conversion import (
+    filter_and_convert_gdf_to_geojson,
+    geojson_to_gdf,
+    gdf_to_geojson_dicts,
+)
+from .io import (
+    get_geojson_from_gpkg,
+    get_gdf_from_gpkg,
+    load_gdf_from_multiple_gz,
+    swap_coordinates,
+    save_geojson,
+)
+from .heights import (
+    extract_building_heights_from_gdf,
+    extract_building_heights_from_geotiff,
+    complement_building_heights_from_gdf,
+)
+from .selection import (
+    filter_buildings,
+    find_building_containing_point,
+    get_buildings_in_drawn_polygon,
+)
+from .overlap import (
+    process_building_footprints_by_overlap,
+)
+from .merge_utils import (
+    merge_gdfs_with_id_conflict_resolution,
+)
+
+__all__ = [
+    # submodules
+    "draw",
+    "utils",
+    "network",
+    "mesh",
+    "raster",
+    "conversion",
+    "io",
+    "heights",
+    "selection",
+    "overlap",
+    "merge_utils",
+    # functions
+    "filter_and_convert_gdf_to_geojson",
+    "geojson_to_gdf",
+    "gdf_to_geojson_dicts",
+    "get_geojson_from_gpkg",
+    "get_gdf_from_gpkg",
+    "load_gdf_from_multiple_gz",
+    "swap_coordinates",
+    "save_geojson",
+    "extract_building_heights_from_gdf",
+    "extract_building_heights_from_geotiff",
+    "complement_building_heights_from_gdf",
+    "filter_buildings",
+    "find_building_containing_point",
+    "get_buildings_in_drawn_polygon",
+    "process_building_footprints_by_overlap",
+    "merge_gdfs_with_id_conflict_resolution",
+]

voxcity/geoprocessor/conversion.py

@@ -0,0 +1,153 @@
+"""
+Conversion utilities between GeoJSON-like features and GeoPandas GeoDataFrames,
+plus helpers to filter and transform geometries for export.
+"""
+
+import json
+from typing import List, Dict
+
+import geopandas as gpd
+import pandas as pd
+from shapely.geometry import Polygon, shape
+
+
+def filter_and_convert_gdf_to_geojson(gdf, rectangle_vertices):
+    """
+    Filter a GeoDataFrame by a bounding rectangle and convert to GeoJSON format.
+
+    This function performs spatial filtering on a GeoDataFrame using a bounding rectangle,
+    and converts the filtered data to GeoJSON format. It handles both Polygon and MultiPolygon
+    geometries, splitting MultiPolygons into separate Polygon features.
+
+    Args:
+        gdf (GeoDataFrame): Input GeoDataFrame containing building data
+            Must have 'geometry' and 'height' columns
+            Any CRS is accepted, will be converted to WGS84 if needed
+        rectangle_vertices (list): List of (lon, lat) tuples defining the bounding rectangle
+            Must be in WGS84 (EPSG:4326) coordinate system
+            Must form a valid rectangle (4 vertices, clockwise or counterclockwise)
+
+    Returns:
+        list: List of GeoJSON features within the bounding rectangle
+            Each feature contains:
+            - geometry: Polygon coordinates in WGS84
+            - properties: Dictionary with 'height', 'confidence', and 'id'
+            - type: Always "Feature"
+
+    Memory Optimization:
+        - Uses spatial indexing for efficient filtering
+        - Downcasts numeric columns to save memory
+        - Cleans up intermediate data structures
+        - Splits MultiPolygons into separate features
+    """
+    if gdf.crs != 'EPSG:4326':
+        gdf = gdf.to_crs(epsg=4326)
+
+    gdf['height'] = pd.to_numeric(gdf['height'], downcast='float')
+    gdf['confidence'] = -1.0
+
+    rectangle_polygon = Polygon(rectangle_vertices)
+
+    gdf.sindex
+    possible_matches_index = list(gdf.sindex.intersection(rectangle_polygon.bounds))
+    possible_matches = gdf.iloc[possible_matches_index]
+    precise_matches = possible_matches[possible_matches.intersects(rectangle_polygon)]
+    filtered_gdf = precise_matches.copy()
+
+    del gdf, possible_matches, precise_matches
+
+    features = []
+    feature_id = 1
+    for _, row in filtered_gdf.iterrows():
+        geom = row['geometry'].__geo_interface__
+        properties = {
+            'height': row['height'],
+            'confidence': row['confidence'],
+            'id': feature_id
+        }
+
+        if geom['type'] == 'MultiPolygon':
+            for polygon_coords in geom['coordinates']:
+                single_geom = {
+                    'type': 'Polygon',
+                    'coordinates': polygon_coords
+                }
+                feature = {
+                    'type': 'Feature',
+                    'properties': properties.copy(),
+                    'geometry': single_geom
+                }
+                features.append(feature)
+                feature_id += 1
+        elif geom['type'] == 'Polygon':
+            feature = {
+                'type': 'Feature',
+                'properties': properties,
+                'geometry': geom
+            }
+            features.append(feature)
+            feature_id += 1
+        else:
+            pass
+
+    geojson = {
+        'type': 'FeatureCollection',
+        'features': features
+    }
+
+    del filtered_gdf, features
+
+    return geojson["features"]
+
+
+def geojson_to_gdf(geojson_data, id_col='id'):
+    """
+    Convert a list of GeoJSON-like dict features into a GeoDataFrame.
+
+    This function takes a list of GeoJSON feature dictionaries (Fiona-like format)
+    and converts them into a GeoDataFrame, handling geometry conversion and property
+    extraction. It ensures each feature has a unique identifier.
+    """
+    geometries = []
+    all_props = []
+
+    for i, feature in enumerate(geojson_data):
+        geom = feature.get('geometry')
+        shapely_geom = shape(geom) if geom else None
+
+        props = feature.get('properties', {})
+        if id_col not in props:
+            props[id_col] = i
+
+        geometries.append(shapely_geom)
+        all_props.append(props)
+
+    gdf = gpd.GeoDataFrame(all_props, geometry=geometries, crs="EPSG:4326")
+    return gdf
+
+
+def gdf_to_geojson_dicts(gdf, id_col='id'):
+    """
+    Convert a GeoDataFrame to a list of dicts similar to GeoJSON features.
+    """
+    records = gdf.to_dict(orient='records')
+    features = []
+
+    for rec in records:
+        geom = rec.pop('geometry', None)
+        if geom is not None:
+            geom = geom.__geo_interface__
+
+        _ = rec.get(id_col, None)
+        props = {k: v for k, v in rec.items() if k != id_col}
+
+        feature = {
+            'type': 'Feature',
+            'properties': props,
+            'geometry': geom
+        }
+        features.append(feature)
+
+    return features
+
+

voxcity/geoprocessor/draw.py

@@ -24,7 +24,7 @@ Dependencies:
 """
 
 import math
-from pyproj import Proj, transform
+from pyproj import Transformer
 from ipyleaflet import (
     Map, 
     DrawControl, 
@@ -45,6 +45,14 @@ from IPython.display import display, clear_output
 
 from .utils import get_coordinates_from_cityname
 
+# Import VoxCity for type checking (avoid circular import with TYPE_CHECKING)
+try:
+    from typing import TYPE_CHECKING
+    if TYPE_CHECKING:
+        from ..models import VoxCity
+except ImportError:
+    pass
+
 def rotate_rectangle(m, rectangle_vertices, angle):
     """
     Project rectangle to Mercator, rotate, and re-project to lat-lon coordinates.
@@ -82,12 +90,12 @@ def rotate_rectangle(m, rectangle_vertices, angle):
         print("Draw a rectangle first!")
         return
 
-    # Define projections - need to convert between coordinate systems for accurate rotation
-    wgs84 = Proj(init='epsg:4326')  # WGS84 lat-lon (standard GPS coordinates)
-    mercator = Proj(init='epsg:3857')  # Web Mercator (projection used by most web maps)
+    # Define transformers (modern pyproj API)
+    to_merc = Transformer.from_crs("EPSG:4326", "EPSG:3857", always_xy=True)
+    to_wgs84 = Transformer.from_crs("EPSG:3857", "EPSG:4326", always_xy=True)
 
     # Project vertices from WGS84 to Web Mercator for proper distance calculations
-    projected_vertices = [transform(wgs84, mercator, lon, lat) for lon, lat in rectangle_vertices]
+    projected_vertices = [to_merc.transform(lon, lat) for lon, lat in rectangle_vertices]
 
     # Calculate the centroid to use as rotation center
     centroid_x = sum(x for x, y in projected_vertices) / len(projected_vertices)
@@ -114,7 +122,7 @@ def rotate_rectangle(m, rectangle_vertices, angle):
         rotated_vertices.append((new_x, new_y))
 
     # Convert coordinates back to WGS84 (lon/lat)
-    new_vertices = [transform(mercator, wgs84, x, y) for x, y in rotated_vertices]
+    new_vertices = [to_wgs84.transform(x, y) for x, y in rotated_vertices]
 
     # Create and add new polygon layer to map
     polygon = LeafletPolygon(
@@ -358,7 +366,7 @@ def center_location_map_cityname(cityname, east_west_length, north_south_length,
 
     return m, rectangle_vertices
 
-def display_buildings_and_draw_polygon(building_gdf=None, rectangle_vertices=None, zoom=17):
+def display_buildings_and_draw_polygon(city=None, building_gdf=None, rectangle_vertices=None, zoom=17):
     """
     Displays building footprints and enables polygon drawing on an interactive map.
     
@@ -384,13 +392,18 @@ def display_buildings_and_draw_polygon(building_gdf=None, rectangle_vertices=Non
        - Support for both building data and rectangle bounds
 
     Args:
+        city (VoxCity, optional): A VoxCity object from which to extract building_gdf 
+            and rectangle_vertices. If provided, these values will be used unless 
+            explicitly overridden by the building_gdf or rectangle_vertices parameters.
         building_gdf (GeoDataFrame, optional): A GeoDataFrame containing building footprints.
             Must have geometry column with Polygon type features.
             Geometries should be in [lon, lat] coordinate order.
-            If None, only the base map is displayed.
+            If None and city is provided, uses city.extras['building_gdf'].
+            If None and no city provided, only the base map is displayed.
         rectangle_vertices (list, optional): List of [lon, lat] coordinates defining rectangle corners.
             Used to set the initial map view extent.
             Takes precedence over building_gdf for determining map center.
+            If None and city is provided, uses city.extras['rectangle_vertices'].
         zoom (int): Initial zoom level for the map. Default=17.
             Range: 0 (most zoomed out) to 18 (most zoomed in).
             Default of 17 is optimized for building-level detail.
@@ -401,6 +414,16 @@ def display_buildings_and_draw_polygon(building_gdf=None, rectangle_vertices=Non
             - drawn_polygons: List of dictionaries with 'id', 'vertices', and 'color' keys for all drawn polygons.
               Each polygon has a unique ID and color for easy identification.
 
+    Examples:
+        Using a VoxCity object:
+        >>> m, polygons = display_buildings_and_draw_polygon(city=my_city)
+        
+        Using explicit parameters:
+        >>> m, polygons = display_buildings_and_draw_polygon(building_gdf=buildings, rectangle_vertices=rect)
+        
+        Override specific parameters from VoxCity:
+        >>> m, polygons = display_buildings_and_draw_polygon(city=my_city, zoom=15)
+
     Note:
         - Building footprints are displayed in blue with 20% opacity
         - Only simple Polygon geometries are supported (no MultiPolygons)
@@ -410,6 +433,18 @@ def display_buildings_and_draw_polygon(building_gdf=None, rectangle_vertices=Non
         - Each polygon gets a unique ID and different colors for easy identification
         - Use get_polygon_vertices() helper function to extract specific polygon data
     """
+    # ---------------------------------------------------------
+    # 0. Extract data from VoxCity object if provided
+    # ---------------------------------------------------------
+    if city is not None:
+        # Extract building_gdf if not explicitly provided
+        if building_gdf is None:
+            building_gdf = city.extras.get('building_gdf', None)
+        
+        # Extract rectangle_vertices if not explicitly provided
+        if rectangle_vertices is None:
+            rectangle_vertices = city.extras.get('rectangle_vertices', None)
+    
     # ---------------------------------------------------------
     # 1. Determine a suitable map center via bounding box logic
     # ---------------------------------------------------------
@@ -514,7 +549,7 @@ def display_buildings_and_draw_polygon(building_gdf=None, rectangle_vertices=Non
 
     return m, drawn_polygons
 
-def draw_additional_buildings(building_gdf=None, initial_center=None, zoom=17, rectangle_vertices=None):
+def draw_additional_buildings(city=None, building_gdf=None, initial_center=None, zoom=17, rectangle_vertices=None):
     """
     Creates an interactive map for drawing building footprints with height input.
     
@@ -530,8 +565,12 @@ def draw_additional_buildings(building_gdf=None, initial_center=None, zoom=17, r
     - Building is added to GeoDataFrame and displayed on map
     
     Args:
+        city (VoxCity, optional): A VoxCity object from which to extract building_gdf 
+            and rectangle_vertices. If provided, these values will be used unless 
+            explicitly overridden by the other parameters.
         building_gdf (GeoDataFrame, optional): Existing building footprints to display.
-            If None, creates a new empty GeoDataFrame.
+            If None and city is provided, uses city.extras['building_gdf'].
+            If None and no city provided, creates a new empty GeoDataFrame.
             Expected columns: ['id', 'height', 'min_height', 'geometry', 'building_id']
             - 'id': Integer ID from data sources (e.g., OSM building id)
             - 'height': Building height in meters (set by user input)
@@ -541,18 +580,29 @@ def draw_additional_buildings(building_gdf=None, initial_center=None, zoom=17, r
         initial_center (tuple, optional): Initial map center as (lon, lat).
             If None, centers on existing buildings or defaults to (-100, 40).
         zoom (int): Initial zoom level (default=17).
+        rectangle_vertices (list, optional): List of [lon, lat] coordinates defining rectangle corners.
+            If None and city is provided, uses city.extras['rectangle_vertices'].
     
     Returns:
         tuple: (map_object, updated_building_gdf)
             - map_object: ipyleaflet Map instance with drawing controls
             - updated_building_gdf: GeoDataFrame that automatically updates when buildings are added
     
-    Example:
-        >>> # Start with empty buildings
+    Examples:
+        Using a VoxCity object:
+        >>> m, buildings = draw_additional_buildings(city=my_city)
+        
+        Start with empty buildings:
         >>> m, buildings = draw_additional_buildings()
         >>> # Draw buildings on the map...
         >>> print(buildings)  # Will contain all drawn buildings
     """
+    # Extract data from VoxCity object if provided
+    if city is not None:
+        if building_gdf is None:
+            building_gdf = city.extras.get('building_gdf', None)
+        if rectangle_vertices is None:
+            rectangle_vertices = city.extras.get('rectangle_vertices', None)
     
     # Initialize or copy the building GeoDataFrame
     if building_gdf is None:

voxcity/geoprocessor/heights.py

@@ -0,0 +1,199 @@
+"""
+Height extraction and complement utilities for building footprints.
+"""
+
+from typing import List, Dict
+
+import numpy as np
+import geopandas as gpd
+import pandas as pd
+from shapely.errors import GEOSException
+from shapely.geometry import shape
+from rtree import index
+import rasterio
+from pyproj import Transformer, CRS
+
+
+def extract_building_heights_from_gdf(gdf_0: gpd.GeoDataFrame, gdf_1: gpd.GeoDataFrame) -> gpd.GeoDataFrame:
+    """
+    Extract building heights from one GeoDataFrame and apply them to another based on spatial overlap.
+    """
+    gdf_primary = gdf_0.copy()
+    gdf_ref = gdf_1.copy()
+
+    if 'height' not in gdf_primary.columns:
+        gdf_primary['height'] = 0.0
+    if 'height' not in gdf_ref.columns:
+        gdf_ref['height'] = 0.0
+
+    count_0 = 0
+    count_1 = 0
+    count_2 = 0
+
+    spatial_index = index.Index()
+    for i, geom in enumerate(gdf_ref.geometry):
+        if geom.is_valid:
+            spatial_index.insert(i, geom.bounds)
+
+    for idx_primary, row in gdf_primary.iterrows():
+        if row['height'] <= 0 or pd.isna(row['height']):
+            count_0 += 1
+            geom = row.geometry
+
+            overlapping_height_area = 0
+            overlapping_area = 0
+
+            potential_matches = list(spatial_index.intersection(geom.bounds))
+
+            for ref_idx in potential_matches:
+                if ref_idx >= len(gdf_ref):
+                    continue
+
+                ref_row = gdf_ref.iloc[ref_idx]
+                try:
+                    if geom.intersects(ref_row.geometry):
+                        overlap_area = geom.intersection(ref_row.geometry).area
+                        overlapping_height_area += ref_row['height'] * overlap_area
+                        overlapping_area += overlap_area
+                except GEOSException:
+                    try:
+                        fixed_ref_geom = ref_row.geometry.buffer(0)
+                        if geom.intersects(fixed_ref_geom):
+                            overlap_area = geom.intersection(fixed_ref_geom).area
+                            overlapping_height_area += ref_row['height'] * overlap_area
+                            overlapping_area += overlap_area
+                    except Exception:
+                        print(f"Failed to fix polygon")
+                    continue
+
+            if overlapping_height_area > 0:
+                count_1 += 1
+                new_height = overlapping_height_area / overlapping_area
+                gdf_primary.at[idx_primary, 'height'] = new_height
+            else:
+                count_2 += 1
+                gdf_primary.at[idx_primary, 'height'] = np.nan
+
+    if count_0 > 0:
+        print(f"For {count_1} of these building footprints without height, values from the complementary source were assigned.")
+        print(f"For {count_2} of these building footprints without height, no data exist in complementary data.")
+
+    return gdf_primary
+
+
+def complement_building_heights_from_gdf(gdf_0, gdf_1, primary_id='id', ref_id='id'):
+    """
+    Vectorized approach with GeoPandas to compute weighted heights and add non-intersecting buildings.
+    Returns a single combined GeoDataFrame.
+    """
+    gdf_primary = gdf_0.copy()
+    gdf_ref = gdf_1.copy()
+
+    if 'height' not in gdf_primary.columns:
+        gdf_primary['height'] = 0.0
+    if 'height' not in gdf_ref.columns:
+        gdf_ref['height'] = 0.0
+
+    gdf_primary = gdf_primary.rename(columns={'height': 'height_primary'})
+    gdf_ref = gdf_ref.rename(columns={'height': 'height_ref'})
+
+    intersect_gdf = gpd.overlay(gdf_primary, gdf_ref, how='intersection')
+    intersect_gdf['intersect_area'] = intersect_gdf.area
+    intersect_gdf['height_area'] = intersect_gdf['height_ref'] * intersect_gdf['intersect_area']
+
+    group_cols = {
+        'height_area': 'sum',
+        'intersect_area': 'sum'
+    }
+    grouped = intersect_gdf.groupby(f'{primary_id}_1').agg(group_cols)
+    grouped['weighted_height'] = grouped['height_area'] / grouped['intersect_area']
+
+    gdf_primary = gdf_primary.merge(grouped['weighted_height'],
+                                    left_on=primary_id,
+                                    right_index=True,
+                                    how='left')
+
+    zero_or_nan_mask = (gdf_primary['height_primary'] == 0) | (gdf_primary['height_primary'].isna())
+    valid_weighted_height_mask = zero_or_nan_mask & gdf_primary['weighted_height'].notna()
+    gdf_primary.loc[valid_weighted_height_mask, 'height_primary'] = gdf_primary.loc[valid_weighted_height_mask, 'weighted_height']
+    gdf_primary['height_primary'] = gdf_primary['height_primary'].fillna(np.nan)
+
+    sjoin_gdf = gpd.sjoin(gdf_ref, gdf_primary, how='left', predicate='intersects')
+    non_intersect_mask = sjoin_gdf[f'{primary_id}_right'].isna()
+    non_intersect_ids = sjoin_gdf[non_intersect_mask][f'{ref_id}_left'].unique()
+    gdf_ref_non_intersect = gdf_ref[gdf_ref[ref_id].isin(non_intersect_ids)]
+    gdf_ref_non_intersect = gdf_ref_non_intersect.rename(columns={'height_ref': 'height'})
+
+    gdf_primary = gdf_primary.rename(columns={'height_primary': 'height'})
+    if 'weighted_height' in gdf_primary.columns:
+        gdf_primary.drop(columns='weighted_height', inplace=True)
+
+    final_gdf = pd.concat([gdf_primary, gdf_ref_non_intersect], ignore_index=True)
+
+    count_total = len(gdf_primary)
+    count_0 = len(gdf_primary[zero_or_nan_mask])
+    count_1 = len(gdf_primary[valid_weighted_height_mask])
+    count_2 = count_0 - count_1
+    count_3 = len(gdf_ref_non_intersect)
+    count_4 = count_3
+    height_mask = gdf_ref_non_intersect['height'].notna() & (gdf_ref_non_intersect['height'] > 0)
+    count_5 = len(gdf_ref_non_intersect[height_mask])
+    count_6 = count_4 - count_5
+    final_height_mask = final_gdf['height'].notna() & (final_gdf['height'] > 0)
+    count_7 = len(final_gdf[final_height_mask])
+    count_8 = len(final_gdf)
+
+    if count_0 > 0:
+        print(f"{count_0} of the total {count_total} building footprints from base data source did not have height data.")
+        print(f"For {count_1} of these building footprints without height, values from complementary data were assigned.")
+        print(f"For the rest {count_2}, no data exists in complementary data.")
+        print(f"Footprints of {count_3} buildings were added from the complementary source.")
+        print(f"Of these {count_4} additional building footprints, {count_5} had height data while {count_6} had no height data.")
+        print(f"In total, {count_7} buildings had height data out of {count_8} total building footprints.")
+
+    return final_gdf
+
+
+def extract_building_heights_from_geotiff(geotiff_path, gdf):
+    """
+    Extract building heights from a GeoTIFF raster for building footprints in a GeoDataFrame.
+    """
+    gdf = gdf.copy()
+
+    count_0 = 0
+    count_1 = 0
+    count_2 = 0
+
+    with rasterio.open(geotiff_path) as src:
+        transformer = Transformer.from_crs(CRS.from_epsg(4326), src.crs, always_xy=True)
+
+        mask_condition = (gdf.geometry.geom_type == 'Polygon') & ((gdf.get('height', 0) <= 0) | gdf.get('height').isna())
+        buildings_to_process = gdf[mask_condition]
+        count_0 = len(buildings_to_process)
+
+        for idx, row in buildings_to_process.iterrows():
+            coords = list(row.geometry.exterior.coords)
+            transformed_coords = [transformer.transform(lon, lat) for lon, lat in coords]
+            polygon = shape({"type": "Polygon", "coordinates": [transformed_coords]})
+
+            try:
+                masked_data, _ = rasterio.mask.mask(src, [polygon], crop=True, all_touched=True)
+                heights = masked_data[0][masked_data[0] != src.nodata]
+                if len(heights) > 0:
+                    count_1 += 1
+                    gdf.at[idx, 'height'] = float(np.mean(heights))
+                else:
+                    count_2 += 1
+                    gdf.at[idx, 'height'] = np.nan
+            except ValueError as e:
+                print(f"Error processing building at index {idx}. Error: {str(e)}")
+                gdf.at[idx, 'height'] = None
+
+    if count_0 > 0:
+        print(f"{count_0} of the total {len(gdf)} building footprint from OSM did not have height data.")
+        print(f"For {count_1} of these building footprints without height, values from complementary data were assigned.")
+        print(f"For {count_2} of these building footprints without height, no data exist in complementary data.")
+
+    return gdf
+
+