voxcity 0.3.4__tar.gz → 0.3.6__tar.gz

{voxcity-0.3.4 → voxcity-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: voxcity
-Version: 0.3.4
+Version: 0.3.6
 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>
@@ -48,6 +48,7 @@ Requires-Dist: overturemaps
 Requires-Dist: protobuf==3.20.3
 Requires-Dist: timezonefinder
 Requires-Dist: astral
+Requires-Dist: osmnx
 Provides-Extra: dev
 Requires-Dist: coverage; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
@@ -329,7 +330,7 @@ solar_kwargs = {
 }
 
 # Compute global solar irradiance map (direct + diffuse radiation)
-global_map = get_global_solar_irradiance_using_epw(    
+solar_grid = get_global_solar_irradiance_using_epw(    
     voxcity_grid,                        # 3D voxel grid representing the urban environment
     meshsize,                            # Size of each voxel in meters
     calc_type='instantaneous',           # Calculate instantaneous irradiance at specified time
@@ -344,7 +345,7 @@ solar_kwargs["end_time"] = "01-31 23:00:00" # End time for cumulative calculatio
 solar_kwargs["output_file_name"] = 'cummulative_solar_irradiance',  # Base filename for outputs (without extension)
 
 # Calculate cumulative solar irradiance over the specified time period
-global_map = get_global_solar_irradiance_using_epw(    
+cum_solar_grid = get_global_solar_irradiance_using_epw(    
     voxcity_grid,                        # 3D voxel grid representing the urban environment
     meshsize,                            # Size of each voxel in meters
     calc_type='cumulative',              # Calculate cumulative irradiance over time period instead of instantaneous
@@ -417,6 +418,38 @@ landmark_vis_map = get_landmark_visibility_map(voxcity_grid, building_id_grid, b
   <em>Example Result Saved as OBJ and Rendered in Rhino</em>
 </p>
 
+#### Network Analysis:
+
+```python
+from voxcity.geo.network import get_network_values
+
+network_kwargs = {
+    "network_type": "walk",        # Type of network to download from OSM (walk, drive, all, etc.)
+    "colormap": "magma",          # Matplotlib colormap for visualization
+    "vis_graph": True,            # Whether to display the network visualization
+    "vmin": 0.0,                  # Minimum value for color scaling
+    "vmax": 600000,               # Maximum value for color scaling
+    "edge_width": 2,              # Width of network edges in visualization
+    "alpha": 0.8,                 # Transparency of network edges
+    "zoom": 16                    # Zoom level for basemap
+}
+
+G, edge_gdf = get_network_values(
+    cum_solar_grid,               # Grid of cumulative solar irradiance values
+    rectangle_vertices,           # Coordinates defining simulation domain boundary
+    meshsize,                     # Size of each grid cell in meters
+    value_name='Cumulative Global Solar Irradiance (W/m²·hour)',  # Label for values in visualization
+    **network_kwargs              # Additional visualization and network parameters
+)
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/network.png" alt="Example of Graph Output" width="500">
+</p>
+<p align="center">
+  <em>Example Result Saved as OBJ and Rendered in Rhino</em>
+</p>
+
 ## References of Data Sources
 
 ### Building 

{voxcity-0.3.4 → voxcity-0.3.6}/README.md

@@ -273,7 +273,7 @@ solar_kwargs = {
 }
 
 # Compute global solar irradiance map (direct + diffuse radiation)
-global_map = get_global_solar_irradiance_using_epw(    
+solar_grid = get_global_solar_irradiance_using_epw(    
     voxcity_grid,                        # 3D voxel grid representing the urban environment
     meshsize,                            # Size of each voxel in meters
     calc_type='instantaneous',           # Calculate instantaneous irradiance at specified time
@@ -288,7 +288,7 @@ solar_kwargs["end_time"] = "01-31 23:00:00" # End time for cumulative calculatio
 solar_kwargs["output_file_name"] = 'cummulative_solar_irradiance',  # Base filename for outputs (without extension)
 
 # Calculate cumulative solar irradiance over the specified time period
-global_map = get_global_solar_irradiance_using_epw(    
+cum_solar_grid = get_global_solar_irradiance_using_epw(    
     voxcity_grid,                        # 3D voxel grid representing the urban environment
     meshsize,                            # Size of each voxel in meters
     calc_type='cumulative',              # Calculate cumulative irradiance over time period instead of instantaneous
@@ -361,6 +361,38 @@ landmark_vis_map = get_landmark_visibility_map(voxcity_grid, building_id_grid, b
   <em>Example Result Saved as OBJ and Rendered in Rhino</em>
 </p>
 
+#### Network Analysis:
+
+```python
+from voxcity.geo.network import get_network_values
+
+network_kwargs = {
+    "network_type": "walk",        # Type of network to download from OSM (walk, drive, all, etc.)
+    "colormap": "magma",          # Matplotlib colormap for visualization
+    "vis_graph": True,            # Whether to display the network visualization
+    "vmin": 0.0,                  # Minimum value for color scaling
+    "vmax": 600000,               # Maximum value for color scaling
+    "edge_width": 2,              # Width of network edges in visualization
+    "alpha": 0.8,                 # Transparency of network edges
+    "zoom": 16                    # Zoom level for basemap
+}
+
+G, edge_gdf = get_network_values(
+    cum_solar_grid,               # Grid of cumulative solar irradiance values
+    rectangle_vertices,           # Coordinates defining simulation domain boundary
+    meshsize,                     # Size of each grid cell in meters
+    value_name='Cumulative Global Solar Irradiance (W/m²·hour)',  # Label for values in visualization
+    **network_kwargs              # Additional visualization and network parameters
+)
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/network.png" alt="Example of Graph Output" width="500">
+</p>
+<p align="center">
+  <em>Example Result Saved as OBJ and Rendered in Rhino</em>
+</p>
+
 ## References of Data Sources
 
 ### Building 

{voxcity-0.3.4 → voxcity-0.3.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "voxcity"
-version = "0.3.4"
+version = "0.3.6"
 requires-python = ">=3.10,<3.13"
 classifiers = [
     "Programming Language :: Python :: 3.10",
@@ -50,6 +50,7 @@ dependencies = [
     "protobuf==3.20.3",
     "timezonefinder",
     "astral",
+    "osmnx",
 ]
 
 [project.optional-dependencies]

voxcity-0.3.6/src/voxcity/geo/__init_.py

@@ -0,0 +1,4 @@
+from .draw import *
+from .grid import *
+from .utils import *
+from .network import *

{voxcity-0.3.4 → voxcity-0.3.6}/src/voxcity/geo/grid.py

@@ -4,7 +4,7 @@ This module provides functions for creating and manipulating grids of building h
 
 import numpy as np
 import os
-from shapely.geometry import Polygon
+from shapely.geometry import Polygon, box
 from scipy.ndimage import label, generate_binary_structure
 from pyproj import Geod, Transformer, CRS
 import rasterio
@@ -12,6 +12,7 @@ from affine import Affine
 from shapely.geometry import box
 from scipy.interpolate import griddata
 from shapely.errors import GEOSException
+import geopandas as gpd
 
 from .utils import (
     initialize_geod,
@@ -748,4 +749,60 @@ def create_dem_grid_from_geotiff_polygon(tiff_path, mesh_size, rectangle_vertice
             # Use nearest neighbor interpolation for raw data
             grid = griddata(points, values, (xx, yy), method='nearest')
 
-    return np.flipud(grid)
+    return np.flipud(grid)
+
+def grid_to_geodataframe(grid_ori, rectangle_vertices, meshsize):
+    """Converts a 2D grid to a GeoDataFrame with cell polygons and values.
+    
+    Args:
+        grid: 2D numpy array containing grid values
+        rectangle_vertices: List of [lon, lat] coordinates defining area corners
+        meshsize: Size of each grid cell in meters
+        
+    Returns:
+        GeoDataFrame with columns:
+            - geometry: Polygon geometry of each grid cell
+            - value: Value from the grid
+    """
+    grid = np.flipud(grid_ori.copy())
+    
+    # Extract bounds from rectangle vertices
+    min_lon = min(v[0] for v in rectangle_vertices)
+    max_lon = max(v[0] for v in rectangle_vertices)
+    min_lat = min(v[1] for v in rectangle_vertices)
+    max_lat = max(v[1] for v in rectangle_vertices)
+    
+    rows, cols = grid.shape
+    
+    # Calculate cell sizes in degrees (approximate)
+    # 111,111 meters = 1 degree at equator
+    cell_size_lon = meshsize / (111111 * np.cos(np.mean([min_lat, max_lat]) * np.pi / 180))
+    cell_size_lat = meshsize / 111111
+    
+    # Create lists to store data
+    polygons = []
+    values = []
+    
+    # Create grid cells
+    for i in range(rows):
+        for j in range(cols):
+            # Calculate cell bounds
+            cell_min_lon = min_lon + j * cell_size_lon
+            cell_max_lon = min_lon + (j + 1) * cell_size_lon
+            # Flip vertical axis since grid is stored with origin at top-left
+            cell_min_lat = max_lat - (i + 1) * cell_size_lat
+            cell_max_lat = max_lat - i * cell_size_lat
+            
+            # Create polygon for cell
+            cell_poly = box(cell_min_lon, cell_min_lat, cell_max_lon, cell_max_lat)
+            
+            polygons.append(cell_poly)
+            values.append(grid[i, j])
+    
+    # Create GeoDataFrame
+    gdf = gpd.GeoDataFrame({
+        'geometry': polygons,
+        'value': values
+    }, crs=CRS.from_epsg(4326))
+    
+    return gdf

voxcity-0.3.6/src/voxcity/geo/network.py

@@ -0,0 +1,194 @@
+import contextily as ctx
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import geopandas as gpd
+from shapely.geometry import LineString
+import networkx as nx
+import osmnx as ox
+
+from .grid import grid_to_geodataframe
+
+def calculate_edge_values(G, gdf, value_col='value'):
+    """
+    Calculate average values for graph edges based on intersection with polygons.
+    
+    Parameters:
+    -----------
+    G : NetworkX Graph
+        Input graph with edges to analyze
+    gdf : GeoDataFrame
+        Grid containing polygons with values
+    value_col : str, default 'value'
+        Name of the column containing values in the grid
+        
+    Returns:
+    --------
+    dict
+        Dictionary with edge identifiers (u,v,k) as keys and average values as values
+    """
+    edge_values = {}
+    for u, v, k, data in G.edges(data=True, keys=True):
+        if 'geometry' in data:
+            edge_line = data['geometry']
+        else:
+            start_node = G.nodes[u]
+            end_node = G.nodes[v]
+            edge_line = LineString([(start_node['x'], start_node['y']),
+                                  (end_node['x'], end_node['y'])])
+        
+        intersecting_polys = gdf[gdf.geometry.intersects(edge_line)]
+        
+        if len(intersecting_polys) > 0:
+            total_length = 0
+            weighted_sum = 0
+            
+            for idx, poly in intersecting_polys.iterrows():
+                if pd.isna(poly[value_col]):
+                    continue
+                
+                intersection = edge_line.intersection(poly.geometry)
+                if not intersection.is_empty:
+                    length = intersection.length
+                    total_length += length
+                    weighted_sum += length * poly[value_col]
+            
+            if total_length > 0:
+                avg_value = weighted_sum / total_length
+                edge_values[(u, v, k)] = avg_value
+            else:
+                edge_values[(u, v, k)] = np.nan
+        else:
+            edge_values[(u, v, k)] = np.nan
+    
+    return edge_values
+
+def get_network_values(grid, rectangle_vertices, meshsize, value_name='value', **kwargs):
+    """
+    Analyze and visualize network values based on grid intersections.
+    
+    Parameters:
+    -----------
+    grid : GeoDataFrame
+        Input grid with geometries and values
+    rectangle_vertices : list
+        List of coordinates defining the bounding box vertices
+    meshsize : float
+        Size of the mesh grid
+    value_name : str, default 'value'
+        Name of the column containing values in the grid
+    **kwargs : dict
+        Optional arguments including:
+        - network_type : str, default 'walk'
+            Type of network to download ('walk', 'drive', 'all', etc.)
+        - vis_graph : bool, default True
+            Whether to visualize the graph
+        - colormap : str, default 'viridis'
+            Matplotlib colormap name for visualization
+        - vmin : float, optional
+            Minimum value for color scaling
+        - vmax : float, optional
+            Maximum value for color scaling
+        - edge_width : float, default 1
+            Width of the edges in visualization
+        - fig_size : tuple, default (15,15)
+            Figure size for visualization
+        - zoom : int, default 16
+            Zoom level for the basemap
+        - basemap_style : ctx.providers, default CartoDB.Positron
+            Contextily basemap provider
+        - save_path : str, optional
+            Path to save the output GeoPackage
+        
+    Returns:
+    --------
+    tuple : (NetworkX Graph, GeoDataFrame)
+        Returns the processed graph and edge GeoDataFrame
+    """
+    # Set default values for optional arguments
+    defaults = {
+        'network_type': 'walk',
+        'vis_graph': True,
+        'colormap': 'viridis',
+        'vmin': None,
+        'vmax': None,
+        'edge_width': 1,
+        'fig_size': (15,15),
+        'zoom': 16,
+        'basemap_style': ctx.providers.CartoDB.Positron,
+        'save_path': None
+    }
+    
+    # Update defaults with provided kwargs
+    settings = defaults.copy()
+    settings.update(kwargs)
+
+    grid_gdf = grid_to_geodataframe(grid, rectangle_vertices, meshsize)
+    
+    # Extract bounding box coordinates
+    north, south = rectangle_vertices[1][1], rectangle_vertices[0][1]
+    east, west   = rectangle_vertices[2][0], rectangle_vertices[0][0]
+    bbox = (west, south, east, north)
+    
+    # Download the road network
+    G = ox.graph.graph_from_bbox(bbox=bbox, network_type=settings['network_type'], simplify=True)
+    
+    # Calculate edge values using the separate function
+    edge_values = calculate_edge_values(G, grid_gdf, "value")
+    
+    # Add values to the graph
+    nx.set_edge_attributes(G, edge_values, value_name)
+    
+    # Create GeoDataFrame from edges
+    edges_with_values = []
+    for u, v, k, data in G.edges(data=True, keys=True):
+        if 'geometry' in data:
+            edge_line = data['geometry']
+        else:
+            start_node = G.nodes[u]
+            end_node = G.nodes[v]
+            edge_line = LineString([(start_node['x'], start_node['y']),
+                                  (end_node['x'], end_node['y'])])
+        
+        edges_with_values.append({
+            'geometry': edge_line,
+            value_name: data.get(value_name, np.nan),
+            'u': u,
+            'v': v,
+            'key': k
+        })
+    
+    edge_gdf = gpd.GeoDataFrame(edges_with_values)
+    
+    # Set CRS and save if requested
+    if edge_gdf.crs is None:
+        edge_gdf.set_crs(epsg=4326, inplace=True)
+    
+    if settings['save_path']:
+        edge_gdf.to_file(settings['save_path'], driver="GPKG")
+    
+    # Visualize if requested
+    if settings['vis_graph']:
+        edge_gdf_web = edge_gdf.to_crs(epsg=3857)
+        
+        fig, ax = plt.subplots(figsize=settings['fig_size'])
+        
+        plot = edge_gdf_web.plot(column=value_name,
+                                ax=ax,
+                                cmap=settings['colormap'],
+                                legend=True,
+                                vmin=settings['vmin'],
+                                vmax=settings['vmax'],
+                                linewidth=settings['edge_width'],
+                                legend_kwds={'label': value_name,
+                                           'shrink': 0.5})  # Make colorbar 50% smaller
+        
+        ctx.add_basemap(ax,
+                       source=settings['basemap_style'],
+                       zoom=settings['zoom'])
+        
+        ax.set_axis_off()
+        # plt.title(f'Network {value_name} Analysis', pad=20)
+        plt.show()
+    
+    return G, edge_gdf

{voxcity-0.3.4 → voxcity-0.3.6}/src/voxcity/sim/solar.py

@@ -675,11 +675,11 @@ def get_global_solar_irradiance_using_epw(
             return None
         else:
             # Calculate center point of rectangle
-            lats = [coord[0] for coord in rectangle_vertices]
-            lons = [coord[1] for coord in rectangle_vertices]
-            center_lat = (min(lats) + max(lats)) / 2
+            lons = [coord[0] for coord in rectangle_vertices]
+            lats = [coord[1] for coord in rectangle_vertices]
             center_lon = (min(lons) + max(lons)) / 2
-            target_point = (center_lat, center_lon)
+            center_lat = (min(lats) + max(lats)) / 2
+            target_point = (center_lon, center_lat)
 
             # Optional: specify maximum distance in kilometers
             max_distance = 100  # None for no limit
@@ -687,8 +687,8 @@ def get_global_solar_irradiance_using_epw(
             output_dir = kwargs.get("output_dir", "output")
 
             epw_file_path, weather_data, metadata = get_nearest_epw_from_climate_onebuilding(
-                latitude=center_lat,
                 longitude=center_lon,
+                latitude=center_lat,
                 output_dir=output_dir,
                 max_distance=max_distance,
                 extract_zip=True,

voxcity-0.3.6/src/voxcity/utils/__init_.py

@@ -0,0 +1,4 @@
+from .visualization import *
+from .lc import *
+from .weather import *
+from .material import *

voxcity-0.3.6/src/voxcity/utils/material.py

@@ -0,0 +1,139 @@
+import numpy as np
+
+def get_material_dict():
+    """
+    Returns a dictionary mapping material names to their corresponding ID values.
+    """
+    return {
+        "unknown": -3,
+        "brick": -11,  
+        "wood": -12,  
+        "concrete": -13,  
+        "metal": -14,  
+        "stone": -15,  
+        "glass": -16,  
+        "plaster": -17,  
+    }
+
+def get_modulo_numbers(window_ratio):
+    """
+    Determines the appropriate modulo numbers for x, y, z based on window_ratio.
+    
+    Parameters:
+    window_ratio: float between 0 and 1.0
+    
+    Returns:
+    tuple (x_mod, y_mod, z_mod): modulo numbers for each dimension
+    """
+    if window_ratio <= 0.125 + 0.0625:  # around 0.125
+        return (2, 2, 2)
+    elif window_ratio <= 0.25 + 0.125:  # around 0.25
+        combinations = [(2, 2, 1), (2, 1, 2), (1, 2, 2)]
+        return combinations[hash(str(window_ratio)) % len(combinations)]
+    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)]
+    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)]
+    else:  # above 0.875
+        return (1, 1, 1)
+
+def set_building_material_by_id(voxelcity_grid, building_id_grid_ori, ids, mark, window_ratio=0.125, glass_id=-16):
+    """
+    Marks cells in voxelcity_grid based on building IDs and window ratio.
+    Never sets glass_id to cells with maximum z index.
+    
+    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)
+    
+    Returns:
+    Modified voxelcity_grid
+    """
+    building_id_grid = np.flipud(building_id_grid_ori.copy())
+    
+    # Get modulo numbers based on window_ratio
+    x_mod, y_mod, z_mod = get_modulo_numbers(window_ratio)
+    
+    # Get positions where building IDs match
+    building_positions = np.where(np.isin(building_id_grid, ids))
+    
+    # Loop through each position that matches building IDs
+    for i in range(len(building_positions[0])):
+        x, y = building_positions[0][i], building_positions[1][i]
+        z_mask = voxelcity_grid[x, y, :] == -3
+        voxelcity_grid[x, y, z_mask] = mark
+        
+        # Check if x and y meet the modulo conditions
+        if x % x_mod == 0 and y % y_mod == 0:
+            z_mask = voxelcity_grid[x, y, :] == mark
+            if np.any(z_mask):
+                # Find the maximum z index where z_mask is True
+                z_indices = np.where(z_mask)[0]
+                max_z_index = np.max(z_indices)
+                
+                # Create base mask excluding maximum z index
+                base_mask = z_mask.copy()
+                base_mask[max_z_index] = False
+                
+                # Create pattern mask 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:
+                    pattern_mask[valid_z_indices[valid_z_indices % z_mod == 0]] = True
+                
+                # For window_ratio around 0.75, add additional pattern
+                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
+                    pattern_mask = np.logical_or(pattern_mask, additional_pattern)
+                
+                # Final mask combines base_mask and pattern_mask
+                final_glass_mask = np.logical_and(base_mask, pattern_mask)
+                
+                # Set glass_id for all positions in the final mask
+                voxelcity_grid[x, y, final_glass_mask] = glass_id
+    
+    return voxelcity_grid
+
+def set_building_material_by_gdf(voxelcity_grid_ori, building_id_grid, gdf_buildings, material_id_dict=None):
+    """
+    Sets building materials based on a GeoDataFrame containing building information.
+    
+    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)
+    
+    Returns:
+    Modified voxelcity_grid
+    """
+    voxelcity_grid = voxelcity_grid_ori.copy()
+    if material_id_dict == None:
+        material_id_dict = get_material_dict()
+
+    for index, row in gdf_buildings.iterrows():
+        # Access properties
+        osmid = row['building_id']
+        surface_material = row['surface_material']
+        window_ratio = row['window_ratio']
+        if surface_material is None:
+            surface_material = 'unknown'            
+        set_building_material_by_id(voxelcity_grid, building_id_grid, osmid, 
+                                  material_id_dict[surface_material], 
+                                  window_ratio=window_ratio, 
+                                  glass_id=material_id_dict['glass'])
+    
+    return voxelcity_grid