voxcity 0.3.2__py3-none-any.whl → 0.3.3__py3-none-any.whl

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/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

voxcity/sim/solar.py

@@ -16,10 +16,16 @@ def compute_direct_solar_irradiance_map_binary(voxel_data, sun_direction, view_p
     """
     Compute a map of direct solar irradiation accounting for tree transmittance.
 
+    The function:
+    1. Places observers at valid locations (empty voxels above ground)
+    2. Casts rays from each observer in the sun direction
+    3. Computes transmittance through trees using Beer-Lambert law
+    4. Returns a 2D map of transmittance values
+
     Args:
         voxel_data (ndarray): 3D array of voxel values.
         sun_direction (tuple): Direction vector of the sun.
-        view_height_voxel (int): Observer height in voxel units.
+        view_point_height (float): Observer height in meters.
         hit_values (tuple): Values considered non-obstacles if inclusion_mode=False.
         meshsize (float): Size of each voxel in meters.
         tree_k (float): Tree extinction coefficient.
@@ -27,7 +33,7 @@ def compute_direct_solar_irradiance_map_binary(voxel_data, sun_direction, view_p
         inclusion_mode (bool): False here, meaning any voxel not in hit_values is an obstacle.
 
     Returns:
-        ndarray: 2D array of transmittance values (0.0-1.0), NaN = invalid observer.
+        ndarray: 2D array of transmittance values (0.0-1.0), NaN = invalid observer position.
     """
     
     view_height_voxel = int(view_point_height / meshsize)
@@ -35,18 +41,22 @@ def compute_direct_solar_irradiance_map_binary(voxel_data, sun_direction, view_p
     nx, ny, nz = voxel_data.shape
     irradiance_map = np.full((nx, ny), np.nan, dtype=np.float64)
 
-    # Normalize sun direction
+    # Normalize sun direction vector for ray tracing
     sd = np.array(sun_direction, dtype=np.float64)
     sd_len = np.sqrt(sd[0]**2 + sd[1]**2 + sd[2]**2)
     if sd_len == 0.0:
         return np.flipud(irradiance_map)
     sd /= sd_len
 
+    # Process each x,y position in parallel
     for x in prange(nx):
         for y in range(ny):
             found_observer = False
+            # Search upward for valid observer position
             for z in range(1, nz):
+                # Check if current voxel is empty/tree and voxel below is solid
                 if voxel_data[x, y, z] in (0, -2) and voxel_data[x, y, z - 1] not in (0, -2):
+                    # Skip if standing on building/vegetation/water
                     if voxel_data[x, y, z - 1] in (-30, -3, -2):
                         irradiance_map[x, y] = np.nan
                         found_observer = True
@@ -62,12 +72,43 @@ def compute_direct_solar_irradiance_map_binary(voxel_data, sun_direction, view_p
             if not found_observer:
                 irradiance_map[x, y] = np.nan
 
+    # Flip map vertically to match visualization conventions
     return np.flipud(irradiance_map)
 
 def get_direct_solar_irradiance_map(voxel_data, meshsize, azimuth_degrees_ori, elevation_degrees, 
                                   direct_normal_irradiance, show_plot=False, **kwargs):
     """
     Compute direct solar irradiance map with tree transmittance.
+    
+    The function:
+    1. Converts sun angles to direction vector
+    2. Computes binary transmittance map
+    3. Scales by direct normal irradiance and sun elevation
+    4. Optionally visualizes and exports results
+    
+    Args:
+        voxel_data (ndarray): 3D array of voxel values.
+        meshsize (float): Size of each voxel in meters.
+        azimuth_degrees_ori (float): Sun azimuth angle in degrees (0° = North, 90° = East).
+        elevation_degrees (float): Sun elevation angle in degrees above horizon.
+        direct_normal_irradiance (float): Direct normal irradiance in W/m².
+        show_plot (bool): Whether to display visualization.
+        **kwargs: Additional arguments including:
+            - view_point_height (float): Observer height in meters (default: 1.5)
+            - colormap (str): Matplotlib colormap name (default: 'magma')
+            - vmin (float): Minimum value for colormap
+            - vmax (float): Maximum value for colormap
+            - tree_k (float): Tree extinction coefficient (default: 0.6)
+            - tree_lad (float): Leaf area density in m^-1 (default: 1.0)
+            - obj_export (bool): Whether to export as OBJ file
+            - output_directory (str): Directory for OBJ export
+            - output_file_name (str): Filename for OBJ export
+            - dem_grid (ndarray): DEM grid for OBJ export
+            - num_colors (int): Number of colors for OBJ export
+            - alpha (float): Alpha value for OBJ export
+
+    Returns:
+        ndarray: 2D array of direct solar irradiance values (W/m²).
     """
     view_point_height = kwargs.get("view_point_height", 1.5)
     colormap = kwargs.get("colormap", 'magma')
@@ -78,7 +119,8 @@ def get_direct_solar_irradiance_map(voxel_data, meshsize, azimuth_degrees_ori, e
     tree_k = kwargs.get("tree_k", 0.6)
     tree_lad = kwargs.get("tree_lad", 1.0)
 
-    # Convert angles to direction
+    # Convert sun angles to direction vector
+    # Note: azimuth is adjusted by 180° to match coordinate system
     azimuth_degrees = 180 - azimuth_degrees_ori
     azimuth_radians = np.deg2rad(azimuth_degrees)
     elevation_radians = np.deg2rad(elevation_degrees)
@@ -91,14 +133,17 @@ def get_direct_solar_irradiance_map(voxel_data, meshsize, azimuth_degrees_ori, e
     hit_values = (0,)
     inclusion_mode = False
 
+    # Compute transmittance map
     transmittance_map = compute_direct_solar_irradiance_map_binary(
         voxel_data, sun_direction, view_point_height, hit_values, 
         meshsize, tree_k, tree_lad, inclusion_mode
     )
 
+    # Scale by direct normal irradiance and sun elevation
     sin_elev = dz
     direct_map = transmittance_map * direct_normal_irradiance * sin_elev
 
+    # Optional visualization
     if show_plot:
         cmap = plt.cm.get_cmap(colormap).copy()
         cmap.set_bad(color='lightgray')
@@ -135,6 +180,33 @@ def get_direct_solar_irradiance_map(voxel_data, meshsize, azimuth_degrees_ori, e
 def get_diffuse_solar_irradiance_map(voxel_data, meshsize, diffuse_irradiance=1.0, show_plot=False, **kwargs):
     """
     Compute diffuse solar irradiance map using the Sky View Factor (SVF) with tree transmittance.
+
+    The function:
+    1. Computes SVF map accounting for tree transmittance
+    2. Scales SVF by diffuse horizontal irradiance
+    3. Optionally visualizes and exports results
+
+    Args:
+        voxel_data (ndarray): 3D array of voxel values.
+        meshsize (float): Size of each voxel in meters.
+        diffuse_irradiance (float): Diffuse horizontal irradiance in W/m².
+        show_plot (bool): Whether to display visualization.
+        **kwargs: Additional arguments including:
+            - view_point_height (float): Observer height in meters (default: 1.5)
+            - colormap (str): Matplotlib colormap name (default: 'magma')
+            - vmin (float): Minimum value for colormap
+            - vmax (float): Maximum value for colormap
+            - tree_k (float): Tree extinction coefficient
+            - tree_lad (float): Leaf area density in m^-1
+            - obj_export (bool): Whether to export as OBJ file
+            - output_directory (str): Directory for OBJ export
+            - output_file_name (str): Filename for OBJ export
+            - dem_grid (ndarray): DEM grid for OBJ export
+            - num_colors (int): Number of colors for OBJ export
+            - alpha (float): Alpha value for OBJ export
+
+    Returns:
+        ndarray: 2D array of diffuse solar irradiance values (W/m²).
     """
 
     view_point_height = kwargs.get("view_point_height", 1.5)
@@ -152,6 +224,7 @@ def get_diffuse_solar_irradiance_map(voxel_data, meshsize, diffuse_irradiance=1.
     SVF_map = get_sky_view_factor_map(voxel_data, meshsize, **svf_kwargs)
     diffuse_map = SVF_map * diffuse_irradiance
 
+    # Optional visualization
     if show_plot:
         vmin = kwargs.get("vmin", 0.0)
         vmax = kwargs.get("vmax", diffuse_irradiance)
@@ -201,18 +274,35 @@ def get_global_solar_irradiance_map(
     """
     Compute global solar irradiance (direct + diffuse) on a horizontal plane at each valid observer location.
 
-    No mode/hit_values/inclusion_mode needed. Uses the updated direct and diffuse functions.
+    The function:
+    1. Computes direct solar irradiance map
+    2. Computes diffuse solar irradiance map
+    3. Combines maps and optionally visualizes/exports results
 
     Args:
         voxel_data (ndarray): 3D voxel array.
         meshsize (float): Voxel size in meters.
-        azimuth_degrees (float): Sun azimuth angle in degrees.
-        elevation_degrees (float): Sun elevation angle in degrees.
-        direct_normal_irradiance (float): DNI in W/m².
-        diffuse_irradiance (float): Diffuse irradiance in W/m².
+        azimuth_degrees (float): Sun azimuth angle in degrees (0° = North, 90° = East).
+        elevation_degrees (float): Sun elevation angle in degrees above horizon.
+        direct_normal_irradiance (float): Direct normal irradiance in W/m².
+        diffuse_irradiance (float): Diffuse horizontal irradiance in W/m².
+        show_plot (bool): Whether to display visualization.
+        **kwargs: Additional arguments including:
+            - view_point_height (float): Observer height in meters (default: 1.5)
+            - colormap (str): Matplotlib colormap name (default: 'magma')
+            - vmin (float): Minimum value for colormap
+            - vmax (float): Maximum value for colormap
+            - tree_k (float): Tree extinction coefficient
+            - tree_lad (float): Leaf area density in m^-1
+            - obj_export (bool): Whether to export as OBJ file
+            - output_directory (str): Directory for OBJ export
+            - output_file_name (str): Filename for OBJ export
+            - dem_grid (ndarray): DEM grid for OBJ export
+            - num_colors (int): Number of colors for OBJ export
+            - alpha (float): Alpha value for OBJ export
 
     Returns:
-        ndarray: 2D array of global solar irradiance (W/m²).
+        ndarray: 2D array of global solar irradiance values (W/m²).
     """    
     
     colormap = kwargs.get("colormap", 'magma')
@@ -242,12 +332,13 @@ def get_global_solar_irradiance_map(
         **direct_diffuse_kwargs
     )
 
-    # Sum the two
+    # Sum the two components
     global_map = direct_map + diffuse_map
 
     vmin = kwargs.get("vmin", np.nanmin(global_map))
     vmax = kwargs.get("vmax", np.nanmax(global_map))
 
+    # Optional visualization
     if show_plot:
         cmap = plt.cm.get_cmap(colormap).copy()
         cmap.set_bad(color='lightgray')
@@ -286,7 +377,19 @@ def get_global_solar_irradiance_map(
 def get_solar_positions_astral(times, lat, lon):
     """
     Compute solar azimuth and elevation using Astral for given times and location.
-    Times must be timezone-aware.
+    
+    The function:
+    1. Creates an Astral observer at the specified location
+    2. Computes sun position for each timestamp
+    3. Returns DataFrame with azimuth and elevation angles
+    
+    Args:
+        times (DatetimeIndex): Array of timezone-aware datetime objects.
+        lat (float): Latitude in degrees.
+        lon (float): Longitude in degrees.
+
+    Returns:
+        DataFrame: DataFrame with columns 'azimuth' and 'elevation' containing solar positions.
     """
     observer = Observer(latitude=lat, longitude=lon)
     df_pos = pd.DataFrame(index=times, columns=['azimuth', 'elevation'], dtype=float)
@@ -309,27 +412,43 @@ def get_cumulative_global_solar_irradiance(
     **kwargs
 ):
     """
-    Compute cumulative global solar irradiance over a specified period using data from an EPW file,
-    accounting for tree transmittance.
+    Compute cumulative global solar irradiance over a specified period using data from an EPW file.
+
+    The function:
+    1. Filters EPW data for specified time period
+    2. Computes sun positions for each timestep
+    3. Calculates and accumulates global irradiance maps
+    4. Handles tree transmittance and visualization
 
     Args:
         voxel_data (ndarray): 3D array of voxel values.
         meshsize (float): Size of each voxel in meters.
-        start_time (str): Start time in format 'MM-DD HH:MM:SS' (no year).
-        end_time (str): End time in format 'MM-DD HH:MM:SS' (no year).
-        direct_normal_irradiance_scaling (float): Scaling factor for DNI.
-        diffuse_irradiance_scaling (float): Scaling factor for DHI.
+        df (DataFrame): EPW weather data.
+        lat (float): Latitude in degrees.
+        lon (float): Longitude in degrees.
+        tz (float): Timezone offset in hours.
+        direct_normal_irradiance_scaling (float): Scaling factor for direct normal irradiance.
+        diffuse_irradiance_scaling (float): Scaling factor for diffuse horizontal irradiance.
         **kwargs: Additional arguments including:
-            - view_point_height (float): Observer height in meters
-            - tree_k (float): Tree extinction coefficient (default: 0.5)
-            - tree_lad (float): Leaf area density in m^-1 (default: 1.0)
-            - download_nearest_epw (bool): Whether to download nearest EPW file
-            - epw_file_path (str): Path to EPW file
+            - view_point_height (float): Observer height in meters (default: 1.5)
+            - start_time (str): Start time in format 'MM-DD HH:MM:SS'
+            - end_time (str): End time in format 'MM-DD HH:MM:SS'
+            - tree_k (float): Tree extinction coefficient
+            - tree_lad (float): Leaf area density in m^-1
             - show_plot (bool): Whether to show final plot
             - show_each_timestep (bool): Whether to show plots for each timestep
+            - colormap (str): Matplotlib colormap name
+            - vmin (float): Minimum value for colormap
+            - vmax (float): Maximum value for colormap
+            - obj_export (bool): Whether to export as OBJ file
+            - output_directory (str): Directory for OBJ export
+            - output_file_name (str): Filename for OBJ export
+            - dem_grid (ndarray): DEM grid for OBJ export
+            - num_colors (int): Number of colors for OBJ export
+            - alpha (float): Alpha value for OBJ export
 
     Returns:
-        ndarray: 2D array of cumulative global solar irradiance (W/m²·hour).
+        ndarray: 2D array of cumulative global solar irradiance values (W/m²·hour).
     """
     view_point_height = kwargs.get("view_point_height", 1.5)
     colormap = kwargs.get("colormap", 'magma')
@@ -346,20 +465,23 @@ def get_cumulative_global_solar_irradiance(
     except ValueError as ve:
         raise ValueError("start_time and end_time must be in format 'MM-DD HH:MM:SS'") from ve
 
-    # Add hour of year column and filter data as before...
+    # Add hour of year column and filter data
     df['hour_of_year'] = (df.index.dayofyear - 1) * 24 + df.index.hour + 1
     
+    # Convert dates to day of year and hour
     start_doy = datetime(2000, start_dt.month, start_dt.day).timetuple().tm_yday
     end_doy = datetime(2000, end_dt.month, end_dt.day).timetuple().tm_yday
     
     start_hour = (start_doy - 1) * 24 + start_dt.hour + 1
     end_hour = (end_doy - 1) * 24 + end_dt.hour + 1
 
+    # Handle period crossing year boundary
     if start_hour <= end_hour:
         df_period = df[(df['hour_of_year'] >= start_hour) & (df['hour_of_year'] <= end_hour)]
     else:
         df_period = df[(df['hour_of_year'] >= start_hour) | (df['hour_of_year'] <= end_hour)]
 
+    # Filter by minutes within start/end hours
     df_period = df_period[
         ((df_period.index.hour != start_dt.hour) | (df_period.index.minute >= start_dt.minute)) &
         ((df_period.index.hour != end_dt.hour) | (df_period.index.minute <= end_dt.minute))
@@ -368,14 +490,14 @@ def get_cumulative_global_solar_irradiance(
     if df_period.empty:
         raise ValueError("No EPW data in the specified period.")
 
-    # Prepare timezone conversion
+    # Handle timezone conversion
     offset_minutes = int(tz * 60)
     local_tz = pytz.FixedOffset(offset_minutes)
     df_period_local = df_period.copy()
     df_period_local.index = df_period_local.index.tz_localize(local_tz)
     df_period_utc = df_period_local.tz_convert(pytz.UTC)
 
-    # Compute solar positions
+    # Compute solar positions for period
     solar_positions = get_solar_positions_astral(df_period_utc.index, lat, lon)
 
     # Create kwargs for diffuse calculation
@@ -393,7 +515,7 @@ def get_cumulative_global_solar_irradiance(
         **diffuse_kwargs
     )
 
-    # Initialize maps
+    # Initialize accumulation maps
     cumulative_map = np.zeros((voxel_data.shape[0], voxel_data.shape[1]))
     mask_map = np.ones((voxel_data.shape[0], voxel_data.shape[1]), dtype=bool)
 
@@ -405,13 +527,14 @@ def get_cumulative_global_solar_irradiance(
         'obj_export': False
     })
 
-    # Iterate through each time step
+    # Process each timestep
     for idx, (time_utc, row) in enumerate(df_period_utc.iterrows()):
+        # Get scaled irradiance values
         DNI = row['DNI'] * direct_normal_irradiance_scaling
         DHI = row['DHI'] * diffuse_irradiance_scaling
         time_local = df_period_local.index[idx]
 
-        # Get solar position
+        # Get solar position for timestep
         solpos = solar_positions.loc[time_utc]
         azimuth_degrees = solpos['azimuth']
         elevation_degrees = solpos['elevation']        
@@ -426,13 +549,13 @@ def get_cumulative_global_solar_irradiance(
             **direct_kwargs
         )
 
-        # Scale base_diffuse_map by actual DHI
+        # Scale base diffuse map by actual DHI
         diffuse_map = base_diffuse_map * DHI
 
-        # Combine direct and diffuse
+        # Combine direct and diffuse components
         global_map = direct_map + diffuse_map
 
-        # Update mask_map
+        # Update valid pixel mask
         mask_map &= ~np.isnan(global_map)
 
         # Replace NaN with 0 for accumulation
@@ -453,7 +576,7 @@ def get_cumulative_global_solar_irradiance(
             plt.colorbar(label='Global Solar Irradiance (W/m²)')
             plt.show()
 
-    # Apply mask
+    # Apply mask to final result
     cumulative_map[~mask_map] = np.nan
 
     # Final visualization
@@ -506,27 +629,38 @@ def get_global_solar_irradiance_using_epw(
     **kwargs
 ):
     """
-    Compute cumulative global solar irradiance over a specified period using data from an EPW file,
-    accounting for tree transmittance.
+    Compute global solar irradiance using EPW weather data, either for a single time or cumulatively over a period.
 
-            voxel_data,             # 3D voxel grid representing the urban environment
-            meshsize,               # Size of each grid cell in meters
-            azimuth_degrees,            # Sun's azimuth angle
-            elevation_degrees,          # Sun's elevation angle
-            direct_normal_irradiance,   # Direct Normal Irradiance value
-            diffuse_irradiance,         # Diffuse irradiance value
-            show_plot=True,            # Display visualization of results
-            **kwargs
-        )
-    if type == 'cummulative':
-            - tree_lad (float): Leaf area density in m^-1 (default: 1.0)
+    The function:
+    1. Optionally downloads and reads EPW weather data
+    2. Handles timezone conversions and solar position calculations
+    3. Computes either instantaneous or cumulative irradiance maps
+    4. Supports visualization and export options
+
+    Args:
+        voxel_data (ndarray): 3D array of voxel values.
+        meshsize (float): Size of each voxel in meters.
+        calc_type (str): 'instantaneous' or 'cumulative'.
+        direct_normal_irradiance_scaling (float): Scaling factor for direct normal irradiance.
+        diffuse_irradiance_scaling (float): Scaling factor for diffuse horizontal irradiance.
+        **kwargs: Additional arguments including:
             - download_nearest_epw (bool): Whether to download nearest EPW file
             - epw_file_path (str): Path to EPW file
-            - show_plot (bool): Whether to show final plot
-            - show_each_timestep (bool): Whether to show plots for each timestep
+            - rectangle_vertices (list): List of (lat,lon) coordinates for EPW download
+            - output_dir (str): Directory for EPW download
+            - calc_time (str): Time for instantaneous calculation ('MM-DD HH:MM:SS')
+            - start_time (str): Start time for cumulative calculation
+            - end_time (str): End time for cumulative calculation
+            - view_point_height (float): Observer height in meters
+            - tree_k (float): Tree extinction coefficient
+            - tree_lad (float): Leaf area density in m^-1
+            - show_plot (bool): Whether to show visualization
+            - show_each_timestep (bool): Whether to show timestep plots
+            - colormap (str): Matplotlib colormap name
+            - obj_export (bool): Whether to export as OBJ file
 
     Returns:
-        ndarray: 2D array of cumulative global solar irradiance (W/m²·hour).
+        ndarray: 2D array of solar irradiance values (W/m²).
     """
     view_point_height = kwargs.get("view_point_height", 1.5)
     colormap = kwargs.get("colormap", 'magma')

voxcity/sim/view.py

@@ -2,15 +2,43 @@
 
 This module provides functionality to compute and visualize:
 - Green View Index (GVI): Measures visibility of green elements like trees and vegetation
-- Sky View Index (SVI): Measures visibility of open sky from street level
+- Sky View Index (SVI): Measures visibility of open sky from street level 
+- Sky View Factor (SVF): Measures the ratio of visible sky hemisphere to total hemisphere
 - Landmark Visibility: Measures visibility of specified landmark buildings from different locations
 
 The module uses optimized ray tracing techniques with Numba JIT compilation for efficient computation.
 Key features:
 - Generic ray tracing framework that can be customized for different view indices
 - Parallel processing for fast computation of view maps
+- Tree transmittance modeling using Beer-Lambert law
 - Visualization tools including matplotlib plots and OBJ exports
 - Support for both inclusion and exclusion based visibility checks
+
+The module provides several key functions:
+- trace_ray_generic(): Core ray tracing function that handles tree transmittance
+- compute_vi_generic(): Computes view indices by casting rays in specified directions
+- compute_vi_map_generic(): Generates 2D maps of view indices
+- get_view_index(): High-level function to compute various view indices
+- compute_landmark_visibility(): Computes visibility of landmark buildings
+- get_sky_view_factor_map(): Computes sky view factor maps
+
+The module uses a voxel-based representation where:
+- Empty space is represented by 0
+- Trees are represented by -2 
+- Buildings are represented by -3
+- Other values can be used for different features
+
+Tree transmittance is modeled using the Beer-Lambert law with configurable parameters:
+- tree_k: Static extinction coefficient (default 0.6)
+- tree_lad: Leaf area density in m^-1 (default 1.0)
+
+Additional implementation details:
+- Uses DDA (Digital Differential Analyzer) algorithm for efficient ray traversal
+- Handles edge cases like zero-length rays and division by zero
+- Supports early exit optimizations for performance
+- Provides flexible observer placement rules
+- Includes comprehensive error checking and validation
+- Allows customization of visualization parameters
 """
 
 import numpy as np
@@ -18,20 +46,31 @@ import matplotlib.pyplot as plt
 import matplotlib.patches as mpatches
 from numba import njit, prange
 
-from ..file.geojson import find_building_containing_point
+from ..file.geojson import find_building_containing_point, get_buildings_in_drawn_polygon
 from ..file.obj import grid_to_obj, export_obj
 
 @njit
 def calculate_transmittance(length, tree_k=0.6, tree_lad=1.0):
     """Calculate tree transmittance using the Beer-Lambert law.
     
+    Uses the Beer-Lambert law to model light attenuation through tree canopy:
+    transmittance = exp(-k * LAD * L)
+    where:
+    - k is the extinction coefficient
+    - LAD is the leaf area density
+    - L is the path length through the canopy
+    
     Args:
         length (float): Path length through tree voxel in meters
-        tree_k (float): Static extinction coefficient (default: 0.5)
+        tree_k (float): Static extinction coefficient (default: 0.6)
+            Controls overall light attenuation strength
         tree_lad (float): Leaf area density in m^-1 (default: 1.0)
+            Higher values = denser foliage = more attenuation
     
     Returns:
         float: Transmittance value between 0 and 1
+            1.0 = fully transparent
+            0.0 = fully opaque
     """
     return np.exp(-tree_k * tree_lad * length)
 
@@ -39,9 +78,34 @@ def calculate_transmittance(length, tree_k=0.6, tree_lad=1.0):
 def trace_ray_generic(voxel_data, origin, direction, hit_values, meshsize, tree_k, tree_lad, inclusion_mode=True):
     """Trace a ray through a voxel grid and check for hits with specified values.
     
-    For tree voxels (-2):
-    - If -2 in hit_values: counts obstruction (1 - transmittance) as hit contribution
-    - If -2 not in hit_values: applies transmittance normally
+    Uses DDA (Digital Differential Analyzer) algorithm for efficient ray traversal.
+    Handles tree transmittance using Beer-Lambert law.
+    
+    The DDA algorithm:
+    1. Initializes ray at origin voxel
+    2. Calculates distances to next voxel boundaries in each direction
+    3. Steps to next voxel by choosing smallest distance
+    4. Repeats until hit or out of bounds
+    
+    Tree transmittance:
+    - When ray passes through tree voxels (-2), transmittance is accumulated
+    - Uses Beer-Lambert law with configurable extinction coefficient and leaf area density
+    - Ray is considered blocked if cumulative transmittance falls below 0.01
+    
+    Args:
+        voxel_data (ndarray): 3D array of voxel values
+        origin (ndarray): Starting point (x,y,z) of ray in voxel coordinates
+        direction (ndarray): Direction vector of ray (will be normalized)
+        hit_values (tuple): Values to check for hits
+        meshsize (float): Size of each voxel in meters
+        tree_k (float): Tree extinction coefficient
+        tree_lad (float): Leaf area density in m^-1
+        inclusion_mode (bool): If True, hit_values are hits. If False, hit_values are allowed values.
+    
+    Returns:
+        tuple: (hit_detected, transmittance_value)
+            hit_detected (bool): Whether ray hit a target voxel
+            transmittance_value (float): Cumulative transmittance through trees
     """
     nx, ny, nz = voxel_data.shape
     x0, y0, z0 = origin
@@ -151,9 +215,28 @@ def trace_ray_generic(voxel_data, origin, direction, hit_values, meshsize, tree_
 def compute_vi_generic(observer_location, voxel_data, ray_directions, hit_values, meshsize, tree_k, tree_lad, inclusion_mode=True):
     """Compute view index accounting for tree transmittance.
     
-    For tree voxels (-2):
-    - If -2 in hit_values: counts obstruction (1 - transmittance) as hit contribution
-    - If -2 not in hit_values: applies transmittance normally
+    Casts rays in specified directions and computes visibility index based on hits and transmittance.
+    The view index is the ratio of visible rays to total rays cast, where:
+    - For inclusion mode: Counts hits with target values
+    - For exclusion mode: Counts rays that don't hit obstacles
+    Tree transmittance is handled specially:
+    - In inclusion mode with trees as targets: Uses (1 - transmittance) as contribution
+    - In exclusion mode: Uses transmittance value directly
+    
+    Args:
+        observer_location (ndarray): Observer position (x,y,z) in voxel coordinates
+        voxel_data (ndarray): 3D array of voxel values
+        ray_directions (ndarray): Array of direction vectors for rays
+        hit_values (tuple): Values to check for hits
+        meshsize (float): Size of each voxel in meters
+        tree_k (float): Tree extinction coefficient
+        tree_lad (float): Leaf area density in m^-1
+        inclusion_mode (bool): If True, hit_values are hits. If False, hit_values are allowed values.
+    
+    Returns:
+        float: View index value between 0 and 1
+            0.0 = no visibility in any direction
+            1.0 = full visibility in all directions
     """
     total_rays = ray_directions.shape[0]
     visibility_sum = 0.0
@@ -180,7 +263,31 @@ def compute_vi_generic(observer_location, voxel_data, ray_directions, hit_values
 @njit(parallel=True)
 def compute_vi_map_generic(voxel_data, ray_directions, view_height_voxel, hit_values, 
                           meshsize, tree_k, tree_lad, inclusion_mode=True):
-    """Compute view index map incorporating tree transmittance."""
+    """Compute view index map incorporating tree transmittance.
+    
+    Places observers at valid locations and computes view index for each position.
+    Valid observer locations are:
+    - Empty voxels (0) or tree voxels (-2)
+    - Above non-empty, non-tree voxels
+    - Not above water (7,8,9) or negative values
+    
+    The function processes each x,y position in parallel for efficiency.
+    
+    Args:
+        voxel_data (ndarray): 3D array of voxel values
+        ray_directions (ndarray): Array of direction vectors for rays
+        view_height_voxel (int): Observer height in voxel units
+        hit_values (tuple): Values to check for hits
+        meshsize (float): Size of each voxel in meters
+        tree_k (float): Tree extinction coefficient
+        tree_lad (float): Leaf area density in m^-1
+        inclusion_mode (bool): If True, hit_values are hits. If False, hit_values are allowed values.
+    
+    Returns:
+        ndarray: 2D array of view index values
+            NaN = invalid observer location
+            0.0-1.0 = view index value
+    """
     nx, ny, nz = voxel_data.shape
     vi_map = np.full((nx, ny), np.nan)
 
@@ -188,12 +295,15 @@ def compute_vi_map_generic(voxel_data, ray_directions, view_height_voxel, hit_va
         for y in range(ny):
             found_observer = False
             for z in range(1, nz):
+                # Check for valid observer location
                 if voxel_data[x, y, z] in (0, -2) and voxel_data[x, y, z - 1] not in (0, -2):
+                    # Skip invalid ground types
                     if (voxel_data[x, y, z - 1] in (7, 8, 9)) or (voxel_data[x, y, z - 1] < 0):
                         vi_map[x, y] = np.nan
                         found_observer = True
                         break
                     else:
+                        # Place observer and compute view index
                         observer_location = np.array([x, y, z + view_height_voxel], dtype=np.float64)
                         vi_value = compute_vi_generic(observer_location, voxel_data, ray_directions, 
                                                     hit_values, meshsize, tree_k, tree_lad, inclusion_mode)
@@ -208,6 +318,14 @@ def compute_vi_map_generic(voxel_data, ray_directions, view_height_voxel, hit_va
 def get_view_index(voxel_data, meshsize, mode=None, hit_values=None, inclusion_mode=True, **kwargs):
     """Calculate and visualize a generic view index for a voxel city model.
 
+    This is a high-level function that provides a flexible interface for computing
+    various view indices. It handles:
+    - Mode presets for common indices (green, sky)
+    - Ray direction generation
+    - Tree transmittance parameters
+    - Visualization
+    - Optional OBJ export
+
     Args:
         voxel_data (ndarray): 3D array of voxel values.
         meshsize (float): Size of each voxel in meters.
@@ -321,15 +439,21 @@ def get_view_index(voxel_data, meshsize, mode=None, hit_values=None, inclusion_m
 
     return vi_map
 
-def mark_building_by_id(voxcity_grid, building_id_grid_ori, ids, mark):
+def mark_building_by_id(voxcity_grid_ori, building_id_grid_ori, ids, mark):
     """Mark specific buildings in the voxel grid with a given value.
 
+    Used to identify landmark buildings for visibility analysis.
+    Flips building ID grid vertically to match voxel grid orientation.
+
     Args:
         voxcity_grid (ndarray): 3D array of voxel values
         building_id_grid_ori (ndarray): 2D array of building IDs
         ids (list): List of building IDs to mark
         mark (int): Value to mark the buildings with
     """
+
+    voxcity_grid = voxcity_grid_ori.copy()
+
     # Flip building ID grid vertically to match voxel grid orientation
     building_id_grid = np.flipud(building_id_grid_ori.copy())
 
@@ -342,17 +466,20 @@ def mark_building_by_id(voxcity_grid, building_id_grid_ori, ids, mark):
         # Replace building voxels (-3) with mark value at this x,y position
         z_mask = voxcity_grid[x, y, :] == -3
         voxcity_grid[x, y, z_mask] = mark
+    
+    return voxcity_grid
 
 @njit
 def trace_ray_to_target(voxel_data, origin, target, opaque_values):
     """Trace a ray from origin to target through voxel data.
 
     Uses DDA algorithm to efficiently traverse voxels along ray path.
+    Checks for any opaque voxels blocking the line of sight.
 
     Args:
         voxel_data (ndarray): 3D array of voxel values
-        origin (tuple): Starting point (x,y,z) of ray
-        target (tuple): End point (x,y,z) of ray
+        origin (tuple): Starting point (x,y,z) in voxel coordinates
+        target (tuple): End point (x,y,z) in voxel coordinates
         opaque_values (ndarray): Array of voxel values that block the ray
 
     Returns:
@@ -443,8 +570,11 @@ def trace_ray_to_target(voxel_data, origin, target, opaque_values):
 def compute_visibility_to_all_landmarks(observer_location, landmark_positions, voxel_data, opaque_values):
     """Check if any landmark is visible from the observer location.
 
+    Traces rays to each landmark position until finding one that's visible.
+    Uses optimized ray tracing with early exit on first visible landmark.
+
     Args:
-        observer_location (ndarray): Observer position (x,y,z)
+        observer_location (ndarray): Observer position (x,y,z) in voxel coordinates
         landmark_positions (ndarray): Array of landmark positions
         voxel_data (ndarray): 3D array of voxel values
         opaque_values (ndarray): Array of voxel values that block visibility
@@ -467,6 +597,12 @@ def compute_visibility_map(voxel_data, landmark_positions, opaque_values, view_h
     Places observers at valid locations (empty voxels above ground, excluding building
     roofs and vegetation) and checks visibility to any landmark.
 
+    The function processes each x,y position in parallel for efficiency.
+    Valid observer locations are:
+    - Empty voxels (0) or tree voxels (-2)
+    - Above non-empty, non-tree voxels
+    - Not above water (7,8,9) or negative values
+
     Args:
         voxel_data (ndarray): 3D array of voxel values
         landmark_positions (ndarray): Array of landmark positions
@@ -474,7 +610,10 @@ def compute_visibility_map(voxel_data, landmark_positions, opaque_values, view_h
         view_height_voxel (int): Height offset for observer in voxels
 
     Returns:
-        ndarray: 2D array of visibility values (0 or 1)
+        ndarray: 2D array of visibility values
+            NaN = invalid observer location
+            0 = no landmarks visible
+            1 = at least one landmark visible
     """
     nx, ny, nz = voxel_data.shape
     visibility_map = np.full((nx, ny), np.nan)
@@ -509,6 +648,12 @@ def compute_landmark_visibility(voxel_data, target_value=-30, view_height_voxel=
     Places observers at valid locations and checks visibility to any landmark voxel.
     Generates a binary visibility map and visualization.
 
+    The function:
+    1. Identifies all landmark voxels (target_value)
+    2. Determines which voxel values block visibility
+    3. Computes visibility from each valid observer location
+    4. Generates visualization with legend
+
     Args:
         voxel_data (ndarray): 3D array of voxel values
         target_value (int, optional): Value used to identify landmark voxels. Defaults to -30.
@@ -517,6 +662,9 @@ def compute_landmark_visibility(voxel_data, target_value=-30, view_height_voxel=
 
     Returns:
         ndarray: 2D array of visibility values (0 or 1) with y-axis flipped
+            NaN = invalid observer location
+            0 = no landmarks visible
+            1 = at least one landmark visible
 
     Raises:
         ValueError: If no landmark voxels are found with the specified target_value
@@ -553,7 +701,7 @@ def compute_landmark_visibility(voxel_data, target_value=-30, view_height_voxel=
 
     return np.flipud(visibility_map)
 
-def get_landmark_visibility_map(voxcity_grid, building_id_grid, building_geojson, meshsize, **kwargs):
+def get_landmark_visibility_map(voxcity_grid_ori, building_id_grid, building_geojson, meshsize, **kwargs):
     """Generate a visibility map for landmark buildings in a voxel city.
 
     Places observers at valid locations and checks visibility to any part of the
@@ -590,25 +738,29 @@ def get_landmark_visibility_map(voxcity_grid, building_id_grid, building_geojson
     # Get landmark building IDs either directly or by finding buildings in rectangle
     features = building_geojson
     landmark_ids = kwargs.get('landmark_building_ids', None)
+    landmark_polygon = kwargs.get('landmark_polygon', None)
     if landmark_ids is None:
-        rectangle_vertices = kwargs.get("rectangle_vertices", None)
-        if rectangle_vertices is None:
-            print("Cannot set landmark buildings. You need to input either of rectangle_vertices or landmark_ids.")
-            return None
+        if landmark_polygon is not None:
+            landmark_ids = get_buildings_in_drawn_polygon(building_geojson, landmark_polygon, operation='within')
+        else:
+            rectangle_vertices = kwargs.get("rectangle_vertices", None)
+            if rectangle_vertices is None:
+                print("Cannot set landmark buildings. You need to input either of rectangle_vertices or landmark_ids.")
+                return None
+                
+            # 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
+            center_lon = (min(lons) + max(lons)) / 2
+            target_point = (center_lat, center_lon)
             
-        # 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
-        center_lon = (min(lons) + max(lons)) / 2
-        target_point = (center_lat, center_lon)
-        
-        # Find buildings at center point
-        landmark_ids = find_building_containing_point(features, target_point)
+            # Find buildings at center point
+            landmark_ids = find_building_containing_point(features, target_point)
 
     # Mark landmark buildings in voxel grid with special value
     target_value = -30
-    mark_building_by_id(voxcity_grid, building_id_grid, landmark_ids, target_value)
+    voxcity_grid = mark_building_by_id(voxcity_grid_ori, building_id_grid, landmark_ids, target_value)
     
     # Compute visibility map
     landmark_vis_map = compute_landmark_visibility(voxcity_grid, target_value=target_value, view_height_voxel=view_height_voxel, colormap=colormap)
@@ -641,7 +793,7 @@ def get_landmark_visibility_map(voxcity_grid, building_id_grid, building_geojson
         output_file_name_vox = 'voxcity_' + output_file_name
         export_obj(voxcity_grid, output_dir, output_file_name_vox, meshsize)
 
-    return landmark_vis_map
+    return landmark_vis_map, voxcity_grid
 
 def get_sky_view_factor_map(voxel_data, meshsize, show_plot=False, **kwargs):
     """

{voxcity-0.3.2.dist-info → voxcity-0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: voxcity
-Version: 0.3.2
+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.2.dist-info → voxcity-0.3.3.dist-info}/RECORD

@@ -11,24 +11,24 @@ voxcity/download/overture.py,sha256=R6XtC2iP6Xp6e2Otop4FXs97gCW_bAuFQ_RCOPiHbjo,
 voxcity/download/utils.py,sha256=z6MdPxM96FWQVqvZW2Eg5pMewVHVysUP7F6ueeCwMfI,1375
 voxcity/file/__init_.py,sha256=cVyNyE6axEpSd3CT5hGuMOAlOyU1p8lVP4jkF1-0Ad8,94
 voxcity/file/envimet.py,sha256=s3qw3kI8sO5996xdnB0MgPCCL0PvICoY1NfrtCz51Sw,24182
-voxcity/file/geojson.py,sha256=Wm_ABjG7lRLOWLPxt0vjP0jycomB898wNte3FEtYT_M,22301
+voxcity/file/geojson.py,sha256=tlkE_strKYTB2xCdZmtAUQjqnTqHYKhpylyi4E8yi0A,25205
 voxcity/file/magicavoxel.py,sha256=Fsv7yGRXeKmp82xcG3rOb0t_HtoqltNq2tHl08xVlqY,7500
 voxcity/file/obj.py,sha256=oW-kPoZj53nfmO9tXP3Wvizq6Kkjh-QQR8UBexRuMiI,21609
 voxcity/geo/__init_.py,sha256=rsj0OMzrTNACccdvEfmf632mb03BRUtKLuecppsxX40,62
-voxcity/geo/draw.py,sha256=yRaJHFAztLuFRO6gJtTGqLQPQkLvGrvw3E0fucnbKPQ,9090
+voxcity/geo/draw.py,sha256=tCWg2kPTbZP3wXyGGywB2Hj4viifaG554VDSjMfFWJg,13728
 voxcity/geo/grid.py,sha256=l9iqi2OCmtJixCc3Y3RthF403pdrx6sB0565wZ1uHgM,40042
 voxcity/geo/utils.py,sha256=sR9InBHxV76XjlGPLD7blg_6EjbM0MG5DOyJffhBjWk,19372
 voxcity/sim/__init_.py,sha256=APdkcdaovj0v_RPOaA4SBvFUKT2RM7Hxuuz3Sux4gCo,65
-voxcity/sim/solar.py,sha256=8_qyA3BLiWWr72GtLo490xLYKOnFxi2XXyKQ0sijI3s,24284
+voxcity/sim/solar.py,sha256=VJCWWHxrKSAg-YgajzY1B9bbnBzKybMm7Tw7dBwvoGI,31306
 voxcity/sim/utils.py,sha256=sEYBB2-hLJxTiXQps1_-Fi7t1HN3-1OPOvBCWtgIisA,130
-voxcity/sim/view.py,sha256=IrCJJ7A4nili6SdUWcnhQ_tRHI4Q_eLSLeetdMy8Og0,29451
+voxcity/sim/view.py,sha256=xab2B7mKDTufJnE7UN0aPAvkhoGQuduIXZOkJTuS5fU,36682
 voxcity/utils/__init_.py,sha256=xjEadXQ9wXTw0lsx0JTbyTqASWw0GJLfT6eRr0CyQzw,71
 voxcity/utils/lc.py,sha256=RwPd-VY3POV3gTrBhM7TubgGb9MCd3nVah_G8iUEF7k,11562
 voxcity/utils/visualization.py,sha256=GVERj0noHAvJtDT0fV3K6w7pTfuAUfwKez-UMuEakEg,42214
 voxcity/utils/weather.py,sha256=Qwnr0paGdRQstwD0A9q2QfJIV-aQUyxH-6viRwXOuwM,21482
-voxcity-0.3.2.dist-info/AUTHORS.rst,sha256=m82vkI5QokEGdcHof2OxK39lf81w1P58kG9ZNNAKS9U,175
-voxcity-0.3.2.dist-info/LICENSE,sha256=-hGliOFiwUrUSoZiB5WF90xXGqinKyqiDI2t6hrnam8,1087
-voxcity-0.3.2.dist-info/METADATA,sha256=8cVLI71VkZ74Xk0N5-bnrn1wYRpK8MbnQTLCsD-7Jl8,19876
-voxcity-0.3.2.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-voxcity-0.3.2.dist-info/top_level.txt,sha256=00b2U-LKfDllt6RL1R33MXie5MvxzUFye0NGD96t_8I,8
-voxcity-0.3.2.dist-info/RECORD,,
+voxcity-0.3.3.dist-info/AUTHORS.rst,sha256=m82vkI5QokEGdcHof2OxK39lf81w1P58kG9ZNNAKS9U,175
+voxcity-0.3.3.dist-info/LICENSE,sha256=-hGliOFiwUrUSoZiB5WF90xXGqinKyqiDI2t6hrnam8,1087
+voxcity-0.3.3.dist-info/METADATA,sha256=F5jlTMuhl1a3-SfpO60KbdhCZ-Ke85BDA7w1OpGD8jM,23607
+voxcity-0.3.3.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+voxcity-0.3.3.dist-info/top_level.txt,sha256=00b2U-LKfDllt6RL1R33MXie5MvxzUFye0NGD96t_8I,8
+voxcity-0.3.3.dist-info/RECORD,,