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

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 algorithm to efficiently traverse voxels along ray path.
+    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
+            lons = [coord[0] for coord in rectangle_vertices]
+            lats = [coord[1] for coord in rectangle_vertices]
+            center_lon = (min(lons) + max(lons)) / 2
+            center_lat = (min(lats) + max(lats)) / 2
+            target_point = (center_lon, center_lat)
             
-        # 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/utils/weather.py

@@ -163,14 +163,14 @@ def process_epw(epw_path: Union[str, Path]) -> Tuple[pd.DataFrame, Dict]:
     
     return df, headers
 
-def get_nearest_epw_from_climate_onebuilding(latitude: float, longitude: float, output_dir: str = "./", max_distance: Optional[float] = None, 
+def get_nearest_epw_from_climate_onebuilding(longitude: float, latitude: float, output_dir: str = "./", max_distance: Optional[float] = None, 
                 extract_zip: bool = True, load_data: bool = True) -> Tuple[Optional[str], Optional[pd.DataFrame], Optional[Dict]]:
     """
     Download and process EPW weather file from Climate.OneBuilding.Org based on coordinates.
     
     Args:
-        latitude (float): Latitude of the location
         longitude (float): Longitude of the location
+        latitude (float): Latitude of the location
         output_dir (str): Directory to save the EPW file (defaults to current directory)
         max_distance (float, optional): Maximum distance in kilometers to search for stations
         extract_zip (bool): Whether to extract the ZIP file (default True)
@@ -222,7 +222,7 @@ def get_nearest_epw_from_climate_onebuilding(latitude: float, longitude: float,
         content = re.sub(r'[^\x09\x0A\x0D\x20-\x7E\x85\xA0-\xFF]', '', content)
         return content
 
-    def haversine_distance(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    def haversine_distance(lon1: float, lat1: float, lon2: float, lat2: float) -> float:
         """Calculate the great circle distance between two points on Earth."""
         R = 6371  # Earth's radius in kilometers
         
@@ -281,8 +281,8 @@ def get_nearest_epw_from_climate_onebuilding(latitude: float, longitude: float,
 
         metadata = {
             'url': url,
-            'latitude': lat,
             'longitude': lon,
+            'latitude': lat,
             'elevation': int(extract_value(r'Elevation <b>(-?\d+)</b>', '0')),
             'name': extract_value(r'<b>(.*?)</b>'),
             'wmo': extract_value(r'WMO <b>(\d+)</b>'),
@@ -370,7 +370,7 @@ def get_nearest_epw_from_climate_onebuilding(latitude: float, longitude: float,
             
         # Calculate distances and find nearest station
         stations_with_distances = [
-            (station, haversine_distance(latitude, longitude, station['latitude'], station['longitude']))
+            (station, haversine_distance(longitude, latitude, station['longitude'], station['latitude']))
             for station in all_stations
         ]
         
@@ -445,7 +445,7 @@ def get_nearest_epw_from_climate_onebuilding(latitude: float, longitude: float,
         # Print station information
         print(f"\nDownloaded EPW file for {nearest_station['name']}")
         print(f"Distance: {distance:.2f} km")
-        print(f"Station coordinates: {nearest_station['latitude']}, {nearest_station['longitude']}")
+        print(f"Station coordinates: {nearest_station['longitude']}, {nearest_station['latitude']}")
         if nearest_station['wmo']:
             print(f"WMO: {nearest_station['wmo']}")
         if nearest_station['climate_zone']:
@@ -520,4 +520,4 @@ def read_epw_for_solar_simulation(epw_file_path):
     df = pd.DataFrame(data, columns=['time', 'DNI', 'DHI']).set_index('time')
     df = df.sort_index()
 
-    return df, lat, lon, tz, elevation_m
+    return df, lon, lat, tz, elevation_m

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: voxcity
-Version: 0.3.2
+Version: 0.3.4
 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>
@@ -164,10 +164,10 @@ Define the target area by directly specifying the coordinates of the rectangle v
 
 ```python
 rectangle_vertices = [
-    (47.59830044521263, -122.33587348582083),  # Southwest corner (latitude, longitude)
-    (47.60279755390168, -122.33587348582083),  # Northwest corner (latitude, longitude)
-    (47.60279755390168, -122.32922451417917),  # Northeast corner (latitude, longitude)
-    (47.59830044521263, -122.32922451417917)   # Southeast corner (latitude, longitude)
+    (-122.33587348582083, 47.59830044521263),  # Southwest corner (longitude, latitude)
+    (-122.33587348582083, 47.60279755390168),  # Northwest corner (longitude, latitude) 
+    (-122.32922451417917, 47.60279755390168),  # Northeast corner (longitude, latitude)
+    (-122.32922451417917, 47.59830044521263)   # Southeast corner (longitude, latitude)
 ]
 ```
 
@@ -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.4.dist-info/RECORD

@@ -0,0 +1,34 @@
+voxcity/__init__.py,sha256=HJM0D2Mv9qpk4JdVzt2SRAAk-hA1D_pCO0ezZH9F7KA,248
+voxcity/voxcity.py,sha256=ewwSxA_lMIkQ5yiLZutq4UCLfnUm0r5f2Jiy-q6cFm0,32256
+voxcity/download/__init__.py,sha256=OgGcGxOXF4tjcEL6DhOnt13DYPTvOigUelp5xIpTqM0,171
+voxcity/download/eubucco.py,sha256=e1JXBuUfBptSDvNznSGckRs5Xgrj_SAFxk445J_o4KY,14854
+voxcity/download/gee.py,sha256=j7jmzp44T3M6j_4DwhU9Y8Y6gqbZo1zFIlduQPc0jvk,14339
+voxcity/download/mbfp.py,sha256=aQOGKP0pV6J6MCBXG9J6kQX04_S31rMjJEVvgrgOPg4,3942
+voxcity/download/oemj.py,sha256=YlCuWBQfi40gfmwQcGDeHiPOs4Pk_jLZq65d5R3IGMU,7886
+voxcity/download/omt.py,sha256=EjzimZMFXcjWNRlUEwPIjeTmE4rPh_9bjsgZyro8_mo,8819
+voxcity/download/osm.py,sha256=HHSuj6jiQrThrfyJMWHE2nQ0Rqkx4UsXopk8AoNZS6Q,26536
+voxcity/download/overture.py,sha256=daOvsySC2KIcTcMJUSA7XdbMELJuyLAIM2vr1DRLGp0,7714
+voxcity/download/utils.py,sha256=z6MdPxM96FWQVqvZW2Eg5pMewVHVysUP7F6ueeCwMfI,1375
+voxcity/file/__init_.py,sha256=cVyNyE6axEpSd3CT5hGuMOAlOyU1p8lVP4jkF1-0Ad8,94
+voxcity/file/envimet.py,sha256=SPVoSyYTMNyDRDFWsI0YAsIsb6yt_SXZeDUlhyqlEqY,24282
+voxcity/file/geojson.py,sha256=G8jG5Ffh86uhNZBLmr_hgyU9FwGab_tJBePET5DUQYk,24188
+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=roljWXyqYdsWYkmb-5_WNxrJrfV5lnAt8uZblCCo_3Q,13555
+voxcity/geo/grid.py,sha256=YgAityV3KaBsng9R_aDQKRFkdEssv5Yzn5wKCIOJQOQ,34243
+voxcity/geo/utils.py,sha256=1BRHp-DDeOA8HG8jplY7Eo75G3oXkVGL6DGONL4BA8A,19815
+voxcity/sim/__init_.py,sha256=APdkcdaovj0v_RPOaA4SBvFUKT2RM7Hxuuz3Sux4gCo,65
+voxcity/sim/solar.py,sha256=7waUoUMzDBf_Van3qghSG019TrgHgNj-TcVRVf0StuU,31306
+voxcity/sim/utils.py,sha256=sEYBB2-hLJxTiXQps1_-Fi7t1HN3-1OPOvBCWtgIisA,130
+voxcity/sim/view.py,sha256=oq6G-f0Tn-KT0vjYNJfucmOIrv1GNjljhA-zvU4nNoA,36668
+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=fJ2p5susoMgYSBlrmlTlZVUDe9kpQwmLuyv1TgcOnDM,21482
+voxcity-0.3.4.dist-info/AUTHORS.rst,sha256=m82vkI5QokEGdcHof2OxK39lf81w1P58kG9ZNNAKS9U,175
+voxcity-0.3.4.dist-info/LICENSE,sha256=-hGliOFiwUrUSoZiB5WF90xXGqinKyqiDI2t6hrnam8,1087
+voxcity-0.3.4.dist-info/METADATA,sha256=wi1ziMnMN8UpySzEQZpGN6SrUW2ZSkY-gOd4kQ9de0U,23608
+voxcity-0.3.4.dist-info/WHEEL,sha256=A3WOREP4zgxI0fKrHUG8DC8013e3dK3n7a6HDbcEIwE,91
+voxcity-0.3.4.dist-info/top_level.txt,sha256=00b2U-LKfDllt6RL1R33MXie5MvxzUFye0NGD96t_8I,8
+voxcity-0.3.4.dist-info/RECORD,,

{voxcity-0.3.2.dist-info → voxcity-0.3.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.6.0)
+Generator: setuptools (75.7.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

voxcity-0.3.2.dist-info/RECORD

@@ -1,34 +0,0 @@
-voxcity/__init__.py,sha256=HJM0D2Mv9qpk4JdVzt2SRAAk-hA1D_pCO0ezZH9F7KA,248
-voxcity/voxcity.py,sha256=ewwSxA_lMIkQ5yiLZutq4UCLfnUm0r5f2Jiy-q6cFm0,32256
-voxcity/download/__init__.py,sha256=OgGcGxOXF4tjcEL6DhOnt13DYPTvOigUelp5xIpTqM0,171
-voxcity/download/eubucco.py,sha256=vd-LoWwUk1A1WC1cSeJTVRFPlAiU04NyQj3RMjohx4M,15149
-voxcity/download/gee.py,sha256=mHrG8mMhhOAvA6wASurZvUPpCKCcg75GriD6VN8VbCM,14297
-voxcity/download/mbfp.py,sha256=pa5eCw1ANzNIzr1bTcrfzttRtNUjUDS808nDAXEHAag,3942
-voxcity/download/oemj.py,sha256=sJ32-hTIo68Vov7Jqxc-n-6oGOF5LcWc8amwZhgZagc,7886
-voxcity/download/omt.py,sha256=x_oKPLWA0YhhC5BRsiGl5sHPFVG5io9w_-0Uafhihm8,8898
-voxcity/download/osm.py,sha256=h5K2ZWeVBpbN_BeWgujWOiyO6gYysylXvzHE3Kk0zEw,26272
-voxcity/download/overture.py,sha256=R6XtC2iP6Xp6e2Otop4FXs97gCW_bAuFQ_RCOPiHbjo,8079
-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/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/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/utils.py,sha256=sEYBB2-hLJxTiXQps1_-Fi7t1HN3-1OPOvBCWtgIisA,130
-voxcity/sim/view.py,sha256=IrCJJ7A4nili6SdUWcnhQ_tRHI4Q_eLSLeetdMy8Og0,29451
-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,,