Update version to 1.0.22 and enhance sunlight hours functions with location and timezone parameters

Author: kunifujiwara

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "voxcity"
-version = "1.0.21"
+version = "1.0.22"
 description = "voxcity is an easy and one-stop tool to output 3d city models for microclimate simulation by integrating multiple geospatial open-data"
 readme = "README.md"
 license = "MIT"

src/voxcity/simulator_gpu/solar/integration/building.py

@@ -24,6 +24,8 @@
     get_solar_positions_astral,
     compute_boundary_vertical_mask,
     apply_computation_mask_to_faces,
+    get_timezone_offset_from_location,
+    generate_annual_hourly_dataframe,
 )
 
 from .caching import (
@@ -513,20 +515,29 @@ def get_building_sunlight_hours(
     epw_file_path: str = None,
     download_nearest_epw: bool = False,
     dni_threshold: float = 120.0,
+    lon: float = None,
+    lat: float = None,
+    tz: float = None,
     **kwargs
 ):
     """
     GPU-accelerated sunlight hours computation for building surfaces.
     
     Supports PSH (Probable Sunlight Hours) and DSH (Direct Sun Hours) modes.
     
+    **DSH mode** does NOT require an EPW file. Location is automatically
+    extracted from the VoxCity object and timezone is inferred.
+    
     Args:
         voxcity: VoxCity object
         building_svf_mesh: Trimesh object with building surfaces (optional)
         mode: 'PSH' or 'DSH'
-        epw_file_path: Path to EPW file
+        epw_file_path: Path to EPW file (required for PSH, optional for DSH)
         download_nearest_epw: If True, download nearest EPW
         dni_threshold: DNI threshold for PSH mode (default: 120.0 W/m²)
+        lon: Longitude in degrees (optional, extracted from voxcity if not provided)
+        lat: Latitude in degrees (optional, extracted from voxcity if not provided)
+        tz: Timezone offset in hours (optional, inferred from location if not provided)
         **kwargs: Additional parameters
     
     Returns:
@@ -549,16 +560,37 @@ def get_building_sunlight_hours(
     use_sky_patches = kwargs.pop('use_sky_patches', True)
     sky_discretization = kwargs.pop('sky_discretization', 'tregenza')
 
-    # Load EPW data
-    weather_df, lon, lat, tz = load_epw_data(
-        epw_file_path=epw_file_path,
-        download_nearest_epw=download_nearest_epw,
-        voxcity=voxcity,
-        **kwargs
-    )
-    
-    if mode == 'PSH' and 'DNI' not in weather_df.columns:
-        raise ValueError("Weather dataframe must have 'DNI' column for PSH mode.")
+    # Load data depending on mode
+    if mode == 'DSH' and epw_file_path is None and not download_nearest_epw:
+        # DSH mode without EPW: derive location and timezone from voxcity
+        if lat is None or lon is None:
+            _lat, _lon = get_location_from_voxcity(voxcity)
+            if lat is None:
+                lat = _lat
+            if lon is None:
+                lon = _lon
+        if tz is None:
+            tz = get_timezone_offset_from_location(lon, lat)
+        
+        # Generate synthetic annual hourly timestamps
+        weather_df = generate_annual_hourly_dataframe()
+    else:
+        # PSH mode or DSH with EPW provided
+        weather_df, lon_epw, lat_epw, tz_epw = load_epw_data(
+            epw_file_path=epw_file_path,
+            download_nearest_epw=download_nearest_epw,
+            voxcity=voxcity,
+            **kwargs
+        )
+        if lon is None:
+            lon = lon_epw
+        if lat is None:
+            lat = lat_epw
+        if tz is None:
+            tz = tz_epw
+        
+        if mode == 'PSH' and 'DNI' not in weather_df.columns:
+            raise ValueError("Weather dataframe must have 'DNI' column for PSH mode.")
 
     # Filter dataframe
     df_period_utc = filter_df_to_period(weather_df, period_start, period_end, tz)

src/voxcity/simulator_gpu/solar/integration/ground.py

@@ -26,6 +26,9 @@
     load_epw_data,
     get_solar_positions_astral,
     add_metadata_to_array,
+    get_location_from_voxcity,
+    get_timezone_offset_from_location,
+    generate_annual_hourly_dataframe,
 )
 
 from .caching import (
@@ -751,6 +754,9 @@ def get_sunlight_hours(
     download_nearest_epw: bool = False,
     dni_threshold: float = 120.0,
     show_plot: bool = False,
+    lon: float = None,
+    lat: float = None,
+    tz: float = None,
     **kwargs
 ) -> np.ndarray:
     """
@@ -759,16 +765,23 @@ def get_sunlight_hours(
     Supports two modes:
     
     **PSH (Probable Sunlight Hours)**: Uses EPW weather data to account for cloud cover.
+      Requires an EPW file (via epw_file_path or download_nearest_epw).
     
     **DSH (Direct Sun Hours)**: Assumes clear sky for all hours.
+      Does NOT require an EPW file. Location (lon/lat) is automatically
+      extracted from the VoxCity object, and timezone is inferred from
+      the location. These can be overridden via the lon, lat, tz parameters.
     
     Args:
         voxcity: VoxCity object
         mode: 'PSH' (Probable Sunlight Hours) or 'DSH' (Direct Sun Hours)
-        epw_file_path: Path to EPW file
+        epw_file_path: Path to EPW file (required for PSH, optional for DSH)
         download_nearest_epw: If True, download nearest EPW based on location
         dni_threshold: DNI threshold for PSH mode (default: 120.0 W/m², WMO standard)
         show_plot: Whether to display a matplotlib plot
+        lon: Longitude in degrees (optional, extracted from voxcity if not provided)
+        lat: Latitude in degrees (optional, extracted from voxcity if not provided)
+        tz: Timezone offset in hours (optional, inferred from location if not provided)
         **kwargs: Additional parameters
     
     Returns:
@@ -793,20 +806,46 @@ def get_sunlight_hours(
     use_sky_patches = kwargs.pop('use_sky_patches', True)
     sky_discretization = kwargs.pop('sky_discretization', 'tregenza')
 
-    # Load EPW data
-    weather_df, lon, lat, tz = load_epw_data(
-        epw_file_path=epw_file_path,
-        download_nearest_epw=download_nearest_epw,
-        voxcity=voxcity,
-        **kwargs
-    )
-    
-    if progress_report:
-        print(f"  Mode: {mode}")
-        print(f"  Location: lon={lon:.4f}, lat={lat:.4f}, tz={tz}")
-    
-    if mode == 'PSH' and 'DNI' not in weather_df.columns:
-        raise ValueError("Weather dataframe must have 'DNI' column for PSH mode.")
+    # Load data depending on mode
+    if mode == 'DSH' and epw_file_path is None and not download_nearest_epw:
+        # DSH mode without EPW: derive location and timezone from voxcity
+        if lat is None or lon is None:
+            _lat, _lon = get_location_from_voxcity(voxcity)
+            if lat is None:
+                lat = _lat
+            if lon is None:
+                lon = _lon
+        if tz is None:
+            tz = get_timezone_offset_from_location(lon, lat)
+        
+        # Generate synthetic annual hourly timestamps
+        weather_df = generate_annual_hourly_dataframe()
+        
+        if progress_report:
+            print(f"  Mode: {mode} (no EPW file needed)")
+            print(f"  Location: lon={lon:.4f}, lat={lat:.4f}, tz={tz}")
+    else:
+        # PSH mode or DSH with EPW provided
+        weather_df, lon_epw, lat_epw, tz_epw = load_epw_data(
+            epw_file_path=epw_file_path,
+            download_nearest_epw=download_nearest_epw,
+            voxcity=voxcity,
+            **kwargs
+        )
+        # Use EPW values as defaults, but allow user overrides
+        if lon is None:
+            lon = lon_epw
+        if lat is None:
+            lat = lat_epw
+        if tz is None:
+            tz = tz_epw
+        
+        if progress_report:
+            print(f"  Mode: {mode}")
+            print(f"  Location: lon={lon:.4f}, lat={lat:.4f}, tz={tz}")
+        
+        if mode == 'PSH' and 'DNI' not in weather_df.columns:
+            raise ValueError("Weather dataframe must have 'DNI' column for PSH mode.")
 
     # Filter dataframe to period
     df_period_utc = filter_df_to_period(weather_df, period_start, period_end, tz)

src/voxcity/simulator_gpu/solar/integration/utils.py

@@ -302,6 +302,59 @@ def get_hour_range_from_period(start_time: str, end_time: str) -> Tuple[int, int
 # EPW Data Loading
 # =============================================================================
 
+def get_timezone_offset_from_location(lon: float, lat: float) -> float:
+    """
+    Get UTC timezone offset (in hours) from longitude/latitude using timezonefinder.
+    
+    Falls back to a simple longitude-based estimate if timezonefinder is not available.
+    
+    Args:
+        lon: Longitude in degrees
+        lat: Latitude in degrees
+        
+    Returns:
+        Timezone offset in hours (e.g. 9.0 for JST, -5.0 for EST)
+    """
+    try:
+        from timezonefinder import TimezoneFinder
+        import pytz
+        tf = TimezoneFinder()
+        tz_str = tf.timezone_at(lng=lon, lat=lat)
+        if tz_str:
+            timezone = pytz.timezone(tz_str)
+            offset_seconds = timezone.utcoffset(datetime(2020, 6, 15)).total_seconds()
+            return offset_seconds / 3600.0
+    except ImportError:
+        pass
+    # Fallback: estimate from longitude (each 15° ≈ 1 hour)
+    return round(lon / 15.0)
+
+
+def generate_annual_hourly_dataframe(year: int = 2020):
+    """
+    Generate a pandas DataFrame with hourly timestamps for a full year.
+    
+    The DataFrame has a datetime index (timezone-naive) and no weather columns,
+    suitable for DSH (Direct Sun Hours) calculations that only need solar
+    position data and do not require weather/EPW data.
+    
+    Args:
+        year: The year to generate timestamps for (default: 2020, a non-leap year
+              is fine since solar geometry varies negligibly between years)
+        
+    Returns:
+        pandas DataFrame with hourly datetime index spanning the full year
+    """
+    import pandas as pd
+    times = pd.date_range(
+        start=f'{year}-01-01 00:00:00',
+        end=f'{year}-12-31 23:00:00',
+        freq='h'
+    )
+    df = pd.DataFrame(index=times)
+    return df
+
+
 def load_epw_data(
     epw_file_path: Optional[str] = None,
     download_nearest_epw: bool = False,