voxcity 0.3.27__tar.gz → 0.4.1__tar.gz

{voxcity-0.3.27 → voxcity-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: voxcity
-Version: 0.3.27
+Version: 0.4.1
 Summary: voxcity is an easy and one-stop tool to output 3d city models for microclimate simulation by integrating multiple geospatial open-data
 Author-email: Kunihiko Fujiwara <kunihiko@nus.edu.sg>
 Maintainer-email: Kunihiko Fujiwara <kunihiko@nus.edu.sg>
@@ -69,7 +69,7 @@ Requires-Dist: ruff; extra == "dev"
 
 # VoxCity
 
-**VoxCity** is a Python package that provides a one-stop solution for grid-based 3D city model generation and urban simulation for cities worldwide. It integrates various geospatial datasets—such as building footprints, land cover, canopy height, and digital elevation models (DEMs)—to generate 2D and 3D representations of urban areas. It can export data in formats compatible with popular simulation tools like ENVI-MET, as well as visualization tools like MagicaVoxel, and supports simulations such as sky view index and green view index calculations.
+**voxcity** is a Python package that provides a seamless solution for grid-based 3D city model generation and urban simulation for cities worldwide. VoxCity's generator module automatically downloads building heights, tree canopy heights, land cover, and terrain elevation within a specified target area, and voxelizes buildings, trees, land cover, and terrain to generate an integrated voxel city model. The simulator module enables users to conduct environmental simulations, including solar radiation and view index analyses. Users can export the generated models using several file formats compatible with external software, such as ENVI-met (INX), Blender, and Rhino (OBJ). Try it out using the [Google Colab Demo](https://colab.research.google.com/drive/1Lofd3RawKMr6QuUsamGaF48u2MN0hfrP?usp=sharing) or your local environment.
 
 <!-- <p align="center">
   <picture>
@@ -180,7 +180,7 @@ rectangle_vertices = [
 Use the GUI map interface to draw a rectangular domain of interest.
 
 ```python
-from voxcity.geo.draw import draw_rectangle_map_cityname
+from voxcity.geoprocessor.draw import draw_rectangle_map_cityname
 
 cityname = "tokyo"
 m, rectangle_vertices = draw_rectangle_map_cityname(cityname, zoom=15)
@@ -191,7 +191,7 @@ m
 Choose the width and height in meters and select the center point on the map.
 
 ```python
-from voxcity.geo.draw import center_location_map_cityname
+from voxcity.geoprocessor.draw import center_location_map_cityname
 
 width = 500
 height = 500
@@ -224,7 +224,7 @@ kwargs = {
 Generate voxel data grids and corresponding building geoJSON:
 
 ```python
-from voxcity import get_voxcity
+from voxcity.generator import get_voxcity
 
 voxcity_grid, building_height_grid, building_min_height_grid, \
 building_id_grid, canopy_height_grid, land_cover_grid, dem_grid, \
@@ -245,7 +245,7 @@ building_gdf = get_voxcity(
 [ENVI-MET](https://www.envi-met.com/) is an advanced microclimate simulation software specialized in modeling urban environments. It simulates the interactions between buildings, vegetation, and various climate parameters like temperature, wind flow, humidity, and radiation. The software is used widely in urban planning, architecture, and environmental studies (Commercial, offers educational licenses).
 
 ```python
-from voxcity.file.envimet import export_inx, generate_edb_file
+from voxcity.exporter.envimet import export_inx, generate_edb_file
 
 envimet_kwargs = {
     "output_directory": "output",                     # Directory where output files will be saved
@@ -271,7 +271,7 @@ generate_edb_file(**envimet_kwargs)
 #### OBJ Files:
 
 ```python
-from voxcity.file.obj import export_obj
+from voxcity.exporter.obj import export_obj
 
 output_directory = "output"  # Directory where output files will be saved
 output_file_name = "voxcity" # Base name for the output OBJ file
@@ -295,7 +295,7 @@ The generated OBJ files can be opened and rendered in the following 3D visualiza
 [MagicaVoxel](https://ephtracy.github.io/) is a lightweight and user-friendly voxel art editor. It allows users to create, edit, and render voxel-based 3D models with an intuitive interface, making it perfect for modifying and visualizing voxelized city models. The software is free and available for Windows and Mac.
 
 ```python
-from voxcity.file.magicavoxel import export_magicavoxel_vox
+from voxcity.exporter.magicavoxel import export_magicavoxel_vox
 
 output_path = "output"
 base_filename = "voxcity"
@@ -313,7 +313,7 @@ export_magicavoxel_vox(voxcity_grid, output_path, base_filename=base_filename)
 #### Compute Solar Irradiance:
 
 ```python
-from voxcity.sim.solar import get_global_solar_irradiance_using_epw
+from voxcity.simulator.solar import get_global_solar_irradiance_using_epw
 
 solar_kwargs = {
     "download_nearest_epw": True,  # Whether to automatically download nearest EPW weather file based on location from Climate.OneBuilding.Org
@@ -369,7 +369,7 @@ cum_solar_grid = get_global_solar_irradiance_using_epw(
 #### Compute Green View Index (GVI) and Sky View Index (SVI):
 
 ```python
-from voxcity.sim.view import get_view_index
+from voxcity.simulator.view import get_view_index
 
 view_kwargs = {
     "view_point_height": 1.5,      # Height of observer viewpoint in meters
@@ -401,7 +401,7 @@ svi_grid = get_view_index(voxcity_grid, meshsize, mode='sky', **view_kwargs)
 #### Landmark Visibility Map:
 
 ```python
-from voxcity.sim.view import get_landmark_visibility_map
+from voxcity.simulator.view import get_landmark_visibility_map
 
 # Dictionary of parameters for landmark visibility analysis
 landmark_kwargs = {
@@ -425,7 +425,7 @@ landmark_vis_map = get_landmark_visibility_map(voxcity_grid, building_id_grid, b
 #### Network Analysis:
 
 ```python
-from voxcity.geo.network import get_network_values
+from voxcity.geoprocessor.network import get_network_values
 
 network_kwargs = {
     "network_type": "walk",        # Type of network to download from OSM (walk, drive, all, etc.)

{voxcity-0.3.27 → voxcity-0.4.1}/README.md

@@ -8,7 +8,7 @@
 
 # VoxCity
 
-**VoxCity** is a Python package that provides a one-stop solution for grid-based 3D city model generation and urban simulation for cities worldwide. It integrates various geospatial datasets—such as building footprints, land cover, canopy height, and digital elevation models (DEMs)—to generate 2D and 3D representations of urban areas. It can export data in formats compatible with popular simulation tools like ENVI-MET, as well as visualization tools like MagicaVoxel, and supports simulations such as sky view index and green view index calculations.
+**voxcity** is a Python package that provides a seamless solution for grid-based 3D city model generation and urban simulation for cities worldwide. VoxCity's generator module automatically downloads building heights, tree canopy heights, land cover, and terrain elevation within a specified target area, and voxelizes buildings, trees, land cover, and terrain to generate an integrated voxel city model. The simulator module enables users to conduct environmental simulations, including solar radiation and view index analyses. Users can export the generated models using several file formats compatible with external software, such as ENVI-met (INX), Blender, and Rhino (OBJ). Try it out using the [Google Colab Demo](https://colab.research.google.com/drive/1Lofd3RawKMr6QuUsamGaF48u2MN0hfrP?usp=sharing) or your local environment.
 
 <!-- <p align="center">
   <picture>
@@ -119,7 +119,7 @@ rectangle_vertices = [
 Use the GUI map interface to draw a rectangular domain of interest.
 
 ```python
-from voxcity.geo.draw import draw_rectangle_map_cityname
+from voxcity.geoprocessor.draw import draw_rectangle_map_cityname
 
 cityname = "tokyo"
 m, rectangle_vertices = draw_rectangle_map_cityname(cityname, zoom=15)
@@ -130,7 +130,7 @@ m
 Choose the width and height in meters and select the center point on the map.
 
 ```python
-from voxcity.geo.draw import center_location_map_cityname
+from voxcity.geoprocessor.draw import center_location_map_cityname
 
 width = 500
 height = 500
@@ -163,7 +163,7 @@ kwargs = {
 Generate voxel data grids and corresponding building geoJSON:
 
 ```python
-from voxcity import get_voxcity
+from voxcity.generator import get_voxcity
 
 voxcity_grid, building_height_grid, building_min_height_grid, \
 building_id_grid, canopy_height_grid, land_cover_grid, dem_grid, \
@@ -184,7 +184,7 @@ building_gdf = get_voxcity(
 [ENVI-MET](https://www.envi-met.com/) is an advanced microclimate simulation software specialized in modeling urban environments. It simulates the interactions between buildings, vegetation, and various climate parameters like temperature, wind flow, humidity, and radiation. The software is used widely in urban planning, architecture, and environmental studies (Commercial, offers educational licenses).
 
 ```python
-from voxcity.file.envimet import export_inx, generate_edb_file
+from voxcity.exporter.envimet import export_inx, generate_edb_file
 
 envimet_kwargs = {
     "output_directory": "output",                     # Directory where output files will be saved
@@ -210,7 +210,7 @@ generate_edb_file(**envimet_kwargs)
 #### OBJ Files:
 
 ```python
-from voxcity.file.obj import export_obj
+from voxcity.exporter.obj import export_obj
 
 output_directory = "output"  # Directory where output files will be saved
 output_file_name = "voxcity" # Base name for the output OBJ file
@@ -234,7 +234,7 @@ The generated OBJ files can be opened and rendered in the following 3D visualiza
 [MagicaVoxel](https://ephtracy.github.io/) is a lightweight and user-friendly voxel art editor. It allows users to create, edit, and render voxel-based 3D models with an intuitive interface, making it perfect for modifying and visualizing voxelized city models. The software is free and available for Windows and Mac.
 
 ```python
-from voxcity.file.magicavoxel import export_magicavoxel_vox
+from voxcity.exporter.magicavoxel import export_magicavoxel_vox
 
 output_path = "output"
 base_filename = "voxcity"
@@ -252,7 +252,7 @@ export_magicavoxel_vox(voxcity_grid, output_path, base_filename=base_filename)
 #### Compute Solar Irradiance:
 
 ```python
-from voxcity.sim.solar import get_global_solar_irradiance_using_epw
+from voxcity.simulator.solar import get_global_solar_irradiance_using_epw
 
 solar_kwargs = {
     "download_nearest_epw": True,  # Whether to automatically download nearest EPW weather file based on location from Climate.OneBuilding.Org
@@ -308,7 +308,7 @@ cum_solar_grid = get_global_solar_irradiance_using_epw(
 #### Compute Green View Index (GVI) and Sky View Index (SVI):
 
 ```python
-from voxcity.sim.view import get_view_index
+from voxcity.simulator.view import get_view_index
 
 view_kwargs = {
     "view_point_height": 1.5,      # Height of observer viewpoint in meters
@@ -340,7 +340,7 @@ svi_grid = get_view_index(voxcity_grid, meshsize, mode='sky', **view_kwargs)
 #### Landmark Visibility Map:
 
 ```python
-from voxcity.sim.view import get_landmark_visibility_map
+from voxcity.simulator.view import get_landmark_visibility_map
 
 # Dictionary of parameters for landmark visibility analysis
 landmark_kwargs = {
@@ -364,7 +364,7 @@ landmark_vis_map = get_landmark_visibility_map(voxcity_grid, building_id_grid, b
 #### Network Analysis:
 
 ```python
-from voxcity.geo.network import get_network_values
+from voxcity.geoprocessor.network import get_network_values
 
 network_kwargs = {
     "network_type": "walk",        # Type of network to download from OSM (walk, drive, all, etc.)

{voxcity-0.3.27 → voxcity-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "voxcity"
-version = "0.3.27"
+version = "0.4.01"
 requires-python = ">=3.10,<3.13"
 classifiers = [
     "Programming Language :: Python :: 3.10",

{voxcity-0.3.27 → voxcity-0.4.1}/src/voxcity/exporter/obj.py

@@ -9,7 +9,7 @@ import numpy as np
 import os
 from numba import njit, prange
 import matplotlib.pyplot as plt
-from ..utils.visualization import get_default_voxel_color_map
+from ..utils.visualization import get_voxel_color_map
 
 def convert_colormap_indices(original_map):
     """
@@ -209,7 +209,7 @@ def export_obj(array, output_dir, file_name, voxel_size, voxel_color_map=None):
             If None, uses default color map.
     """
     if voxel_color_map is None:
-        voxel_color_map = get_default_voxel_color_map()
+        voxel_color_map = get_voxel_color_map()
 
     # Extract unique voxel values (excluding zero)
     unique_voxel_values = np.unique(array)

{voxcity-0.3.27 → voxcity-0.4.1}/src/voxcity/geoprocessor/grid.py

@@ -26,7 +26,8 @@ from ..geoprocessor.polygon import (
     filter_buildings, 
     extract_building_heights_from_geotiff, 
     extract_building_heights_from_gdf,
-    complement_building_heights_from_gdf
+    complement_building_heights_from_gdf,
+    process_building_footprints_by_overlap
 )
 from ..utils.lc import (
     get_class_priority, 
@@ -555,6 +556,9 @@ def create_building_height_grid_from_gdf_polygon(
             filtered_gdf = extract_building_heights_from_gdf(filtered_gdf, filtered_gdf_comp)
     elif geotiff_path_comp:
         filtered_gdf = extract_building_heights_from_geotiff(geotiff_path_comp, filtered_gdf)
+    
+    # After filtering and complementing heights, process overlapping buildings
+    filtered_gdf = process_building_footprints_by_overlap(filtered_gdf, overlap_threshold=0.5)
 
     # --------------------------------------------------------------------------
     # 2) PREPARE BUILDING POLYGONS & SPATIAL INDEX

{voxcity-0.3.27 → voxcity-0.4.1}/src/voxcity/geoprocessor/mesh.py

@@ -4,7 +4,7 @@ import matplotlib.colors as mcolors
 import matplotlib.cm as cm
 import matplotlib.pyplot as plt
 
-def create_voxel_mesh(voxel_array, class_id, meshsize=1.0):
+def create_voxel_mesh(voxel_array, class_id, meshsize=1.0, building_id_grid=None):
     """
     Create a mesh from voxels preserving sharp edges, scaled by meshsize.
 
@@ -16,15 +16,21 @@ def create_voxel_mesh(voxel_array, class_id, meshsize=1.0):
         The ID of the class to extract.
     meshsize : float
         The real-world size of each voxel in meters, for x, y, and z.
+    building_id_grid : np.ndarray (2D), optional
+        2D grid of building IDs, shape (X, Y). Used when class_id=-3 (buildings).
 
     Returns
     -------
     mesh : trimesh.Trimesh or None
         The resulting mesh for the given class_id (or None if no voxels).
+        If class_id=-3, mesh.metadata['building_id'] contains building IDs.
     """
     # Find voxels of the current class
     voxel_coords = np.argwhere(voxel_array == class_id)
 
+    if building_id_grid is not None:
+        building_id_grid_flipud = np.flipud(building_id_grid)
+
     if len(voxel_coords) == 0:
         return None
 
@@ -57,8 +63,14 @@ def create_voxel_mesh(voxel_array, class_id, meshsize=1.0):
     vertices = []
     faces = []
     face_normals_list = []
+    building_ids = []  # List to store building IDs for each face
 
     for x, y, z in voxel_coords:
+        # For buildings, get the building ID from the grid
+        building_id = None
+        if class_id == -3 and building_id_grid is not None:
+            building_id = building_id_grid_flipud[x, y]
+            
         # Check each face of the current voxel
         adjacent_coords = [
             (x,   y,   z+1),  # Front
@@ -95,6 +107,10 @@ def create_voxel_mesh(voxel_array, class_id, meshsize=1.0):
                 ])
                 # Add face normals for both triangles
                 face_normals_list.extend([face_normals[face_idx], face_normals[face_idx]])
+                
+                # Store building ID for both triangles if this is a building
+                if class_id == -3 and building_id_grid is not None:
+                    building_ids.extend([building_id, building_id])
 
     if not vertices:
         return None
@@ -112,6 +128,10 @@ def create_voxel_mesh(voxel_array, class_id, meshsize=1.0):
 
     # Merge vertices that are at the same position
     mesh.merge_vertices()
+    
+    # Add building IDs as metadata for buildings
+    if class_id == -3 and building_id_grid is not None and building_ids:
+        mesh.metadata = {'building_id': np.array(building_ids)}
 
     return mesh
 

{voxcity-0.3.27 → voxcity-0.4.1}/src/voxcity/geoprocessor/polygon.py

@@ -19,6 +19,7 @@ from pyproj import Transformer, CRS
 import rasterio
 from rasterio.mask import mask
 import copy
+from rtree import index
 
 from .utils import validate_polygon_coordinates
 
@@ -794,4 +795,97 @@ def get_buildings_in_drawn_polygon(building_gdf, drawn_polygon_vertices,
         else:
             raise ValueError("operation must be 'intersect' or 'within'")
 
-    return included_building_ids
+    return included_building_ids
+
+def process_building_footprints_by_overlap(filtered_gdf, overlap_threshold=0.5):
+    """
+    Process building footprints to merge overlapping buildings.
+    
+    Args:
+        filtered_gdf (geopandas.GeoDataFrame): GeoDataFrame containing building footprints
+        overlap_threshold (float): Threshold for overlap ratio (0.0-1.0) to merge buildings
+        
+    Returns:
+        geopandas.GeoDataFrame: Processed GeoDataFrame with updated IDs
+    """
+    # Make a copy to avoid modifying the original
+    gdf = filtered_gdf.copy()
+    
+    # Ensure 'id' column exists
+    if 'id' not in gdf.columns:
+        gdf['id'] = gdf.index
+    
+    # Calculate areas and sort by area (descending)
+    gdf['area'] = gdf.geometry.area
+    gdf = gdf.sort_values(by='area', ascending=False)
+    gdf = gdf.reset_index(drop=True)
+    
+    # Create spatial index for efficient querying
+    spatial_idx = index.Index()
+    for i, geom in enumerate(gdf.geometry):
+        if geom.is_valid:
+            spatial_idx.insert(i, geom.bounds)
+        else:
+            # Fix invalid geometries
+            fixed_geom = geom.buffer(0)
+            if fixed_geom.is_valid:
+                spatial_idx.insert(i, fixed_geom.bounds)
+    
+    # Track ID replacements to avoid repeated processing
+    id_mapping = {}
+    
+    # Process each building (skip the largest one)
+    for i in range(1, len(gdf)):
+        current_poly = gdf.iloc[i].geometry
+        current_area = gdf.iloc[i].area
+        current_id = gdf.iloc[i]['id']
+        
+        # Skip if already mapped
+        if current_id in id_mapping:
+            continue
+        
+        # Ensure geometry is valid
+        if not current_poly.is_valid:
+            current_poly = current_poly.buffer(0)
+            if not current_poly.is_valid:
+                continue
+        
+        # Find potential overlaps with larger polygons
+        potential_overlaps = [j for j in spatial_idx.intersection(current_poly.bounds) if j < i]
+        
+        for j in potential_overlaps:
+            larger_poly = gdf.iloc[j].geometry
+            larger_id = gdf.iloc[j]['id']
+            
+            # Skip if already processed
+            if larger_id in id_mapping:
+                larger_id = id_mapping[larger_id]
+            
+            # Ensure geometry is valid
+            if not larger_poly.is_valid:
+                larger_poly = larger_poly.buffer(0)
+                if not larger_poly.is_valid:
+                    continue
+            
+            try:
+                # Calculate overlap
+                if current_poly.intersects(larger_poly):
+                    overlap = current_poly.intersection(larger_poly)
+                    overlap_ratio = overlap.area / current_area
+                    
+                    # Replace ID if overlap exceeds threshold
+                    if overlap_ratio > overlap_threshold:
+                        id_mapping[current_id] = larger_id
+                        gdf.at[i, 'id'] = larger_id
+                        break  # Stop at first significant overlap
+            except (GEOSException, ValueError) as e:
+                # Handle geometry errors gracefully
+                continue
+    
+    # Propagate ID changes through the original DataFrame
+    for i, row in filtered_gdf.iterrows():
+        orig_id = row.get('id')
+        if orig_id in id_mapping:
+            filtered_gdf.at[i, 'id'] = id_mapping[orig_id]
+    
+    return filtered_gdf