voxcity 0.3.1__tar.gz → 0.3.3__tar.gz

{voxcity-0.3.1 → voxcity-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: voxcity
-Version: 0.3.1
+Version: 0.3.3
 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>
@@ -305,6 +305,62 @@ export_magicavoxel_vox(voxcity_grid, output_path, base_filename=base_filename)
 
 ### 6. Additional Use Cases
 
+#### Compute Solar Irradiance:
+
+```python
+from voxcity.sim.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
+    "rectangle_vertices": rectangle_vertices,  # Coordinates defining the area of interest for calculation
+    # "epw_file_path": "./output/new.york-downtown.manhattan.heli_ny_usa_1.epw",  # Path to EnergyPlus Weather (EPW) file containing climate data. Set if you already have an EPW file.
+    "calc_time": "01-01 12:00:00",  # Time for instantaneous calculation in format "MM-DD HH:MM:SS"
+    "view_point_height": 1.5,  # Height of view point in meters for calculating solar access. Default: 1.5 m
+    "tree_k": 0.6,    # Static extinction coefficient - controls how much sunlight is blocked by trees (higher = more blocking)
+    "tree_lad": 1.0,    # Leaf area density of trees - density of leaves/branches that affect shading (higher = denser foliage)
+    "dem_grid": dem_grid,      # Digital elevation model grid for terrain heights
+    "colormap": 'magma',       # Matplotlib colormap for visualization. Default: 'viridis'
+    "obj_export": True,        # Whether to export results as 3D OBJ file
+    "output_directory": 'output/test',  # Directory for saving output files
+    "output_file_name": 'instantaneous_solar_irradiance',  # Base filename for outputs (without extension)
+    "alpha": 1.0,             # Transparency of visualization (0.0-1.0)
+    "vmin": 0,               # Minimum value for colormap scaling in visualization
+    # "vmax": 900,             # Maximum value for colormap scaling in visualization
+}
+
+# Compute global solar irradiance map (direct + diffuse radiation)
+global_map = 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
+    direct_normal_irradiance_scaling=1.0, # Scaling factor for direct solar radiation (1.0 = no scaling)
+    diffuse_irradiance_scaling=1.0,      # Scaling factor for diffuse solar radiation (1.0 = no scaling)
+    **solar_kwargs                       # Pass all the parameters defined above
+)
+
+# Adjust parameters for cumulative calculation
+solar_kwargs["start_time"] = "01-01 01:00:00" # Start time for cumulative calculation
+solar_kwargs["end_time"] = "01-31 23:00:00" # End time for cumulative calculation
+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(    
+    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
+    direct_normal_irradiance_scaling=1.0, # Scaling factor for direct solar radiation (1.0 = no scaling)
+    diffuse_irradiance_scaling=1.0,      # Scaling factor for diffuse solar radiation (1.0 = no scaling)
+    **solar_kwargs                       # Pass all the parameters defined above
+)
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/solar.png" alt="Solar Irradiance Maps Rendered in Rhino" width="800">
+</p>
+<p align="center">
+  <em>Example Results Saved as OBJ and Rendered in Rhino</em>
+</p>
+
 #### Compute Green View Index (GVI) and Sky View Index (SVI):
 
 ```python

{voxcity-0.3.1 → voxcity-0.3.3}/README.md

@@ -249,6 +249,62 @@ export_magicavoxel_vox(voxcity_grid, output_path, base_filename=base_filename)
 
 ### 6. Additional Use Cases
 
+#### Compute Solar Irradiance:
+
+```python
+from voxcity.sim.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
+    "rectangle_vertices": rectangle_vertices,  # Coordinates defining the area of interest for calculation
+    # "epw_file_path": "./output/new.york-downtown.manhattan.heli_ny_usa_1.epw",  # Path to EnergyPlus Weather (EPW) file containing climate data. Set if you already have an EPW file.
+    "calc_time": "01-01 12:00:00",  # Time for instantaneous calculation in format "MM-DD HH:MM:SS"
+    "view_point_height": 1.5,  # Height of view point in meters for calculating solar access. Default: 1.5 m
+    "tree_k": 0.6,    # Static extinction coefficient - controls how much sunlight is blocked by trees (higher = more blocking)
+    "tree_lad": 1.0,    # Leaf area density of trees - density of leaves/branches that affect shading (higher = denser foliage)
+    "dem_grid": dem_grid,      # Digital elevation model grid for terrain heights
+    "colormap": 'magma',       # Matplotlib colormap for visualization. Default: 'viridis'
+    "obj_export": True,        # Whether to export results as 3D OBJ file
+    "output_directory": 'output/test',  # Directory for saving output files
+    "output_file_name": 'instantaneous_solar_irradiance',  # Base filename for outputs (without extension)
+    "alpha": 1.0,             # Transparency of visualization (0.0-1.0)
+    "vmin": 0,               # Minimum value for colormap scaling in visualization
+    # "vmax": 900,             # Maximum value for colormap scaling in visualization
+}
+
+# Compute global solar irradiance map (direct + diffuse radiation)
+global_map = 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
+    direct_normal_irradiance_scaling=1.0, # Scaling factor for direct solar radiation (1.0 = no scaling)
+    diffuse_irradiance_scaling=1.0,      # Scaling factor for diffuse solar radiation (1.0 = no scaling)
+    **solar_kwargs                       # Pass all the parameters defined above
+)
+
+# Adjust parameters for cumulative calculation
+solar_kwargs["start_time"] = "01-01 01:00:00" # Start time for cumulative calculation
+solar_kwargs["end_time"] = "01-31 23:00:00" # End time for cumulative calculation
+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(    
+    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
+    direct_normal_irradiance_scaling=1.0, # Scaling factor for direct solar radiation (1.0 = no scaling)
+    diffuse_irradiance_scaling=1.0,      # Scaling factor for diffuse solar radiation (1.0 = no scaling)
+    **solar_kwargs                       # Pass all the parameters defined above
+)
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/solar.png" alt="Solar Irradiance Maps Rendered in Rhino" width="800">
+</p>
+<p align="center">
+  <em>Example Results Saved as OBJ and Rendered in Rhino</em>
+</p>
+
 #### Compute Green View Index (GVI) and Sky View Index (SVI):
 
 ```python

{voxcity-0.3.1 → voxcity-0.3.3}/pyproject.toml

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

{voxcity-0.3.1 → voxcity-0.3.3}/src/voxcity/file/geojson.py

@@ -525,4 +525,75 @@ def find_building_containing_point(features, target_point):
         if polygon.contains(point):
             id_list.append(feature['properties']['id'])
     
-    return id_list
+    return id_list
+
+def get_buildings_in_drawn_polygon(building_geojson, drawn_polygon_vertices, 
+                                   operation='within'):
+    """
+    Given a list of building footprints (in Lat-Lon) and a set of drawn polygon 
+    vertices (also in Lat-Lon), return the building IDs that fall within or 
+    intersect the drawn polygon.
+
+    Args:
+        building_geojson (list): 
+            A list of GeoJSON features, each feature is a dict with:
+            {
+                "type": "Feature",
+                "geometry": {
+                    "type": "Polygon",
+                    "coordinates": [
+                        [
+                            [lat1, lon1], [lat2, lon2], ...
+                        ]
+                    ]
+                },
+                "properties": {
+                    "id": ...
+                    ...
+                }
+            }
+            Note: These coordinates are in (lat, lon) order, not standard (lon, lat).
+
+        drawn_polygon_vertices (list): 
+            A list of (lat, lon) tuples representing the polygon drawn by the user.
+
+        operation (str):
+            Determines how to include buildings. 
+            Use "intersect" to include buildings that intersect the drawn polygon. 
+            Use "within" to include buildings that lie entirely within the drawn polygon.
+
+    Returns:
+        list:
+            A list of building IDs (strings or ints) that satisfy the condition.
+    """
+    # 1. Convert the user-drawn polygon vertices (lat, lon) into a Shapely Polygon.
+    #    Shapely expects (x, y) = (longitude, latitude).
+    #    So we'll do (lon, lat) for each vertex.
+    drawn_polygon_shapely = Polygon([(lon, lat) for (lat, lon) in drawn_polygon_vertices])
+
+    included_building_ids = []
+
+    # 2. Check each building in the GeoJSON
+    for feature in building_geojson:
+        # Skip any feature that is not Polygon
+        if feature['geometry']['type'] != 'Polygon':
+            continue
+
+        # Extract coordinates, which are in [ [lat, lon], [lat, lon], ... ]
+        coords = feature['geometry']['coordinates'][0]
+
+        # Create a Shapely polygon for the building
+        # Convert from (lat, lon) to (lon, lat)
+        building_polygon = Polygon([(lon, lat) for (lat, lon) in coords])
+
+        # 3. Depending on the operation, check the relationship
+        if operation == 'intersect':
+            if building_polygon.intersects(drawn_polygon_shapely):
+                included_building_ids.append(feature['properties'].get('id', None))
+        elif operation == 'within':
+            if building_polygon.within(drawn_polygon_shapely):
+                included_building_ids.append(feature['properties'].get('id', None))
+        else:
+            raise ValueError("operation must be 'intersect' or 'within'")
+
+    return included_building_ids

{voxcity-0.3.1 → voxcity-0.3.3}/src/voxcity/geo/draw.py

@@ -4,10 +4,11 @@ This module provides functions for drawing and manipulating rectangles on maps.
 
 import math
 from pyproj import Proj, transform
-from ipyleaflet import Map, DrawControl, Rectangle
+from ipyleaflet import Map, DrawControl, Rectangle, Polygon as LeafletPolygon
 import ipyleaflet
 from geopy import distance
 from .utils import get_coordinates_from_cityname
+import shapely.geometry as geom
 
 def rotate_rectangle(m, rectangle_vertices, angle):
     """
@@ -222,4 +223,113 @@ def center_location_map_cityname(cityname, east_west_length, north_south_length,
     # Register event handler for drawing actions
     draw_control.on_draw(handle_draw)
 
-    return m, rectangle_vertices
+    return m, rectangle_vertices
+
+def display_buildings_and_draw_polygon(building_geojson, zoom=17):
+    """
+    Displays building footprints (in Lat-Lon order) on an ipyleaflet map,
+    and allows the user to draw a polygon whose vertices are returned
+    in a Python list (also in Lat-Lon).
+
+    Args:
+        building_geojson (list): A list of GeoJSON features (Polygons),
+                                 BUT with coordinates in [lat, lon] order.
+        zoom (int): Initial zoom level for the map. Default=17.
+
+    Returns:
+        (map_object, drawn_polygon_vertices)
+          - map_object: ipyleaflet Map instance
+          - drawn_polygon_vertices: a Python list that gets updated whenever
+            a new polygon is created. The list is in (lat, lon) order.
+    """
+    # ---------------------------------------------------------
+    # 1. Determine a suitable map center via bounding box logic
+    # ---------------------------------------------------------
+    all_lats = []
+    all_lons = []
+    for feature in building_geojson:
+        # Handle only Polygons here; skip MultiPolygon if present
+        if feature['geometry']['type'] == 'Polygon':
+            # Coordinates in this data are [ [lat, lon], [lat, lon], ... ]
+            coords = feature['geometry']['coordinates'][0]  # outer ring
+            all_lats.extend(pt[0] for pt in coords)
+            all_lons.extend(pt[1] for pt in coords)
+
+    if not all_lats or not all_lons:
+        # Fallback: If no footprints or invalid data, pick a default
+        center_lat, center_lon = 40.0, -100.0
+    else:
+        min_lat, max_lat = min(all_lats), max(all_lats)
+        min_lon, max_lon = min(all_lons), max(all_lons)
+        center_lat = (min_lat + max_lat) / 2
+        center_lon = (min_lon + max_lon) / 2
+
+    # Create the ipyleaflet map
+    m = Map(center=(center_lat, center_lon), zoom=zoom, scroll_wheel_zoom=True)
+
+    # -----------------------------------------
+    # 2. Add each building footprint to the map
+    # -----------------------------------------
+    for feature in building_geojson:
+        # Only handle simple Polygons
+        if feature['geometry']['type'] == 'Polygon':
+            coords = feature['geometry']['coordinates'][0]
+            # Because your data is already lat-lon, we do NOT swap:
+            lat_lon_coords = [(c[0], c[1]) for c in coords]
+
+            # Create the polygon layer
+            bldg_layer = LeafletPolygon(
+                locations=lat_lon_coords,
+                color="blue",
+                fill_color="blue",
+                fill_opacity=0.2,
+                weight=2
+            )
+            m.add_layer(bldg_layer)
+
+    # -----------------------------------------------------------------
+    # 3. Enable drawing of polygons, capturing the vertices in Lat-Lon
+    # -----------------------------------------------------------------
+    drawn_polygon_vertices = []  # We'll store the newly drawn polygon's vertices here (lat, lon).
+
+    draw_control = DrawControl(
+        polygon={
+            "shapeOptions": {
+                "color": "#6bc2e5",
+                "fillColor": "#6bc2e5",
+                "fillOpacity": 0.2
+            }
+        },
+        rectangle={},     # Disable rectangles (or enable if needed)
+        circle={},        # Disable circles
+        circlemarker={},  # Disable circlemarkers
+        polyline={},      # Disable polylines
+        marker={}         # Disable markers
+    )
+
+    def handle_draw(self, action, geo_json):
+        """
+        Callback for whenever a shape is created or edited.
+        ipyleaflet's DrawControl returns standard GeoJSON (lon, lat).
+        We'll convert them to (lat, lon).
+        """
+        # Clear any previously stored vertices
+        drawn_polygon_vertices.clear()
+
+        if action == 'created' and geo_json['geometry']['type'] == 'Polygon':
+            # The polygon’s first ring
+            coordinates = geo_json['geometry']['coordinates'][0]
+            print("Vertices of the drawn polygon (Lat-Lon):")
+
+            # By default, drawn polygon coords are [ [lon, lat], [lon, lat], ... ]
+            # The last coordinate repeats the first -> skip it with [:-1]
+            for coord in coordinates[:-1]:
+                lon = coord[0]
+                lat = coord[1]
+                drawn_polygon_vertices.append((lat, lon))
+                print(f" - (lat, lon) = ({lat}, {lon})")
+
+    draw_control.on_draw(handle_draw)
+    m.add_control(draw_control)
+
+    return m, drawn_polygon_vertices